obsidian-ontology-sync
# Obsidian-Ontology Sync
**Philosophy:** Obsidian is PRIMARY (human writes natural notes) → Ontology is DERIVED (machine extracts structure) → Feedback loop improves both
## Core Concept
```
Obsidian Notes (Markdown)
↓ Extract (every 3 hours)
Ontology Graph (Structured)
↓ Query & Analyze
Insights & Suggestions
↓ Feedback
Improved Note Templates
```
## When to Use
| Situation | Action |
|-----------|--------|
| After creating/updating contacts | Run sync to extract entities |
| Before business queries | Sync then query ontology |
| Weekly review | Sync + analyze + get suggestions |
| New project setup | Extract entities + suggest structure |
| Team status tracking | Sync daily-status → ontology → analytics |
## What Gets Extracted
### From Contact Notes (`references/contacts/*.md`)
**Extracts:**
- `Person` entity (name, email, phone)
- `works_at` → `Organization`
- `met_at` → `Event`
- `assigned_to` → `Project` (if mentioned)
- `status` → (prospect, warm_lead, client, etc.)
**Example:**
```markdown
# Alice Johnson
**Email:** alice@company.com
**Company:** Acme Corp
**Met At:** Tech Conference 2026
**Projects:** Project Alpha
## Notes
Great developer, responsive communication.
```
**Becomes:**
```json
{
"entity": {
"id": "person_alice_johnson",
"type": "Person",
"properties": {
"name": "Alice Johnson",
"email": "alice@company.com",
"notes": "Great developer, responsive communication"
}
},
"relations": [
{"from": "person_alice_johnson", "rel": "works_at", "to": "org_acme"},
{"from": "person_alice_johnson", "rel": "met_at", "to": "event_tech_conference_2026"},
{"from": "person_alice_johnson", "rel": "assigned_to", "to": "project_alpha"}
]
}
```
### From Client Notes (`references/clients/*.md`)
**Extracts:**
- `Organization` entity
- `has_contract_value` → number
- `projects` → `Project` entities
- `primary_contact` → `Person`
### From Team Notes (`references/team/*.md`)
**Extracts:**
- `Person` entity
- `works_for` → `Organization`
- `assigned_to` → `Project[]`
- `reports_to` → `Person`
- `response_pattern` → (proactive, reactive, non-responsive)
### From Daily Status (`daily-status/YYYY-MM-DD/*.md`)
**Extracts:**
- `response_time` property on Person
- `status_update` → `Event`
- `blockers` → `Issue` entities
- `behavioral_pattern` tracking
### From Project Notes (`projects/*.md`)
**Extracts:**
- `Project` entity
- `for_client` → `Organization`
- `team` → `Person[]`
- `status`, `value`, `deadline`
## Sync Process
### 1. Extract Phase (Markdown → Ontology)
```bash
# Run extraction
python3 skills/obsidian-ontology-sync/scripts/sync.py extract
# What it does:
# 1. Scan configured Obsidian directories
# 2. Parse markdown frontmatter + content
# 3. Extract entities (Person, Project, Organization, etc.)
# 4. Extract relationships (works_at, assigned_to, etc.)
# 5. Write to ontology using append-only operations
```
**Detection Rules:**
```python
# Contact files
if file.startswith("references/contacts/"):
entity_type = "Person"
extract_email_from_content()
extract_company_from_property("Company:")
extract_projects_from_links([[Project]])
# Client files
if file.startswith("references/clients/"):
entity_type = "Organization"
extract_contract_value()
extract_projects()
# Team files
if file.startswith("references/team/"):
entity_type = "Person"
role = "team_member"
extract_assignments()
extract_response_patterns()
```
### 2. Analysis Phase (Ontology → Insights)
```bash
# Run analytics
python3 skills/obsidian-ontology-sync/scripts/sync.py analyze
# Generates insights like:
# - "3 team members have no assigned projects"
# - "Contact 'John Doe' missing email address"
# - "Project 'X' has 5 people but no client linked"
# - "10 contacts from AI Summit not linked to follow-up tasks"
```
### 3. Feedback Phase (Insights → Improve PKM)
```bash
# Get suggestions
python3 skills/obsidian-ontology-sync/scripts/sync.py feedback
# Creates:
# - Missing property suggestions
# - Broken link reports
# - Relationship suggestions
# - Template improvements
```
**Example Feedback:**
```markdown
# Sync Feedback - 2026-02-27
## Missing Information (10 items)
- [ ] `Alice Johnson` missing phone number
- [ ] `Bob` missing email in team file
- [ ] Project `Project Alpha` missing deadline
## Suggested Links (5 items)
- [ ] Link `Jane Doe` (TechHub) to organization `TechHub`
- [ ] Link `Eve` to project (found in daily-status but not in team file)
## Relationship Insights
- `Project Alpha` team: Alice, Carol, David (extracted from daily-status)
- Suggest updating project file with team assignments
## Template Suggestions
- Add `Projects: [[]]` field to contact template
- Add `Response Pattern:` field to team template
```
## Configuration
### config.yaml
```yaml
# /root/life/pkm/ontology-sync/config.yaml
obsidian:
vault_path: /root/life/pkm
# What to sync
sources:
contacts:
path: references/contacts
entity_type: Person
extract:
- email_from_content
- company_from_property
- projects_from_links
clients:
path: references/clients
entity_type: Organization
extract:
- contract_value
- projects
- contacts
team:
path: references/team
entity_type: Person
role: team_member
extract:
- assignments
- response_patterns
- reports_to
daily_status:
path: daily-status
extract:
- response_times
- behavioral_patterns
- blockers
ontology:
storage_path: /root/life/pkm/memory/ontology
format: jsonl # or sqlite for scale
# Entity types to track
entities:
- Person
- Organization
- Project
- Event
- Task
# Relationships to extract
relationships:
- works_at
- assigned_to
- met_at
- for_client
- reports_to
- has_task
- blocks
feedback:
output_path: /root/life/pkm/ontology-sync/feedback
generate_reports: true
suggest_templates: true
highlight_missing: true
schedule:
# Run via cron every 3 hours
sync_interval: "0 */3 * * *"
analyze_daily: "0 9 * * *" # 9 AM daily
feedback_weekly: "0 10 * * MON" # Monday 10 AM
```
## Scheduled Sync (Cron Integration)
### Setup Automatic Sync
```bash
# Add to OpenClaw cron
python3 skills/obsidian-ontology-sync/scripts/setup-cron.py
# Or manually via cron tool
cron add \
--schedule "0 */3 * * *" \
--task "python3 skills/obsidian-ontology-sync/scripts/sync.py extract" \
--label "Obsidian → Ontology Sync"
```
**Cron Jobs Created:**
1. **Every 3 hours:** Extract entities from Obsidian → Update ontology
2. **Daily 9 AM:** Run analytics and generate insights
3. **Weekly Monday 10 AM:** Generate feedback report + template suggestions
## Queries (Using Ontology)
Once synced, you can query:
```bash
# All team members on high-value projects
python3 skills/ontology/scripts/ontology.py query \
--type Person \
--where '{"role":"team_member"}' \
--related assigned_to \
--filter '{"type":"Project","value__gt":400000}'
# Contacts from specific event not yet followed up
python3 skills/ontology/scripts/ontology.py query \
--type Person \
--where '{"met_at":"event_tech_conference_2026"}' \
--missing has_task
# Team response patterns
python3 skills/ontology/scripts/ontology.py query \
--type Person \
--where '{"role":"team_member"}' \
--aggregate response_pattern
# Projects by client
python3 skills/ontology/scripts/ontology.py query \
--type Project \
--group-by for_client \
--count
```
## Feedback Loop Examples
### Example 1: Missing Email Detection
**Ontology finds:** Person entity with no email property
**Feedback generated:**
```markdown
## Missing Contact Information
The following team members are missing email addresses:
- [ ] Bob (`references/team/Bob.md`)
- [ ] Lucky (`references/team/Lucky.md`)
**Suggestion:** Add email field to team member template:
\`\`\`markdown
**Email:**
\`\`\`
```
### Example 2: Broken Project Links
**Ontology finds:** Person assigned_to Project that doesn't exist
**Feedback generated:**
```markdown
## Broken Project References
Found references to projects that don't have dedicated files:
- [ ] "Project Epsilon" mentioned in team files but no `projects/Project Epsilon.md`
- [ ] "Project Delta Tata DT" assigned but no project file
**Suggestion:** Create project files with template
```
### Example 3: Relationship Discovery
**Ontology finds:** Multiple people working at same company
**Feedback generated:**
```markdown
## Suggested Company Grouping
Found 3 contacts at "TechHub":
- Jane Doe
- [2 others from daily-status mentions]
**Suggestion:** Create `references/clients/TechHub.md` and link contacts
```
## Integration with Daily Workflow
### Morning Routine (9 AM)
```bash
# Cron runs analysis
# Generates daily-insights.md with:
- Response rate from yesterday's status requests
- Projects needing attention (blockers mentioned)
- Contacts to follow up (met > 3 days ago, no task)
```
### Weekly Review (Monday 10 AM)
```bash
# Cron generates weekly feedback
# Creates suggestions for:
- Missing information to fill in
- Broken links to fix
- New templates to adopt
- Relationship insights
```
### On-Demand Queries
```bash
# Before a meeting
"Show me all interactions with Client X"
# Resource planning
"Which team members are on <3 projects?"
# Sales pipeline
"Contacts met at conferences in last 30 days without follow-up"
```
## Benefits
### ✅ For You
1. **Zero Extra Work:** Just keep writing normal Obsidian notes
2. **Automatic Structure:** Ontology extracted automatically
3. **Powerful Queries:** Find patterns across all your data
4. **Quality Improvement:** Feedback loop catches missing info
5. **No Double Entry:** Single source of truth (Obsidian)
### ✅ For Team Management
- Track who's on which project (auto-extracted)
- Monitor response patterns (from daily-status)
- Identify unbalanced workloads
- Find blockers across projects
### ✅ For Sales/BD
- Track contact network (who you met, where, when)
- Follow-up reminders (contacted >7 days ago)
- Relationship mapping (who knows who)
- Pipeline insights (prospects → warm → clients)
### ✅ For Finance
- Project valuations (extracted from client notes)
- Team cost allocation (people → projects → revenue)
- Revenue forecasting (active projects × value)
## File Structure After Sync
```
/root/life/pkm/
├── references/
│ ├── contacts/ # Source notes (you write these)
│ ├── clients/ # Source notes
│ └── team/ # Source notes
├── daily-status/ # Source notes
├── projects/ # Source notes
│
├── memory/ontology/ # Generated ontology
│ ├── graph.jsonl # Entity/relation storage
│ └── schema.yaml # Type definitions
│
└── ontology-sync/ # Sync outputs
├── config.yaml # Your config
├── feedback/
│ ├── daily-insights.md
│ ├── weekly-feedback.md
│ └── suggestions.md
└── logs/
└── sync-YYYY-MM-DD.log
```
## Advanced: Bidirectional Sync
**Future capability:**
Update Obsidian notes FROM ontology insights:
```bash
# Automatically add missing fields
python3 skills/obsidian-ontology-sync/scripts/sync.py apply-feedback
# What it does:
# - Adds missing email field to contact notes
# - Creates suggested project files
# - Links related entities
# - Updates frontmatter
```
**Safety:** Always creates backup before modifying files.
## Comparison with Alternatives
| Approach | Pros | Cons |
|----------|------|------|
| **Manual ontology** | Full control | Too much work, falls behind |
| **Obsidian only** | Simple | No structured queries |
| **Ontology only** | Powerful queries | Not human-friendly |
| **This skill** | Best of both | Initial setup needed |
## Getting Started
### 1. Install Dependencies
```bash
# Already have ontology skill installed
clawhub install obsidian # If not already installed
```
### 2. Create Config
```bash
python3 skills/obsidian-ontology-sync/scripts/init.py
# Creates:
# - config.yaml with your vault path
# - ontology directory structure
# - cron jobs
```
### 3. Run First Sync
```bash
# Manual first sync to test
python3 skills/obsidian-ontology-sync/scripts/sync.py extract --dry-run
# See what would be extracted
# Review, then run for real:
python3 skills/obsidian-ontology-sync/scripts/sync.py extract
```
### 4. Enable Automatic Sync
```bash
python3 skills/obsidian-ontology-sync/scripts/setup-cron.py
# Confirms cron jobs:
# ✓ Sync every 3 hours
# ✓ Daily analysis at 9 AM
# ✓ Weekly feedback Monday 10 AM
```
### 5. Query Your Data
```bash
# Try some queries
python3 skills/obsidian-ontology-sync/scripts/query.py "team members on high value projects"
```
## Troubleshooting
### Extraction Issues
```bash
# Dry run to see what would be extracted
python3 skills/obsidian-ontology-sync/scripts/sync.py extract --dry-run --verbose
# Check specific file
python3 skills/obsidian-ontology-sync/scripts/debug.py \
--file references/contacts/Alice.md
```
### Query Not Finding Data
```bash
# Check what's in ontology
python3 skills/ontology/scripts/ontology.py query --type Person
# Verify sync ran
cat /root/life/pkm/ontology-sync/logs/sync-latest.log
```
### Feedback Not Generated
```bash
# Manually run analysis
python3 skills/obsidian-ontology-sync/scripts/sync.py analyze
python3 skills/obsidian-ontology-sync/scripts/sync.py feedback
```
## Version History
- **1.0.0** (2026-02-27) - Initial version with extraction, analysis, feedback loop
---
**Author:** Built for team management, contact tracking, and business intelligence at scale
**License:** MIT
**Tags:** obsidian, ontology, knowledge-graph, pkm, automation, sync
标签
skill
ai
