Obsidian Ontology Sync

---
name: obsidian-ontology-sync
description: Bidirectional sync between Obsidian PKM (human-friendly notes) and structured ontology (machine-queryable graph). Automatically extracts entities and relationships from markdown, maintains ontology graph, and provides feedback to improve note structure. Run sync every few hours via cron.
metadata:
  {
    "tags": ["obsidian", "ontology", "knowledge-graph", "pkm", "automation"],
    "openclaw":
      {
        "requires": { "skills": ["obsidian", "ontology"] }
      }
  }
---

# 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:** [email protected]
**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": "[email protected]",
      "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 '{"