# Ontology Module - Clean-Room Knowledge Graph

**Zero external dependencies.** SQLite-based. Sovereign Stack compatible.

## Status: ✅ INTEGRATED

**Completed:** 2026-04-27  
**Lines of code:** ~1,100 (schema + engine + NL interface)  
**Test coverage:** 7 query patterns verified

## Files

| File | Lines | Purpose |
|------|-------|---------|
| `schema.sql` | 97 | Database DDL + bootstrap data |
| `engine.py` | 384 | Core CRUD, queries, export |
| `natural_language.py` | 433 | NL interface, no Cypher/Gremlin |
| `README.md` | — | This file |

## Quick Start

```bash
cd /home/hoffmann_admin/.openclaw/shared/ontology

# Test the engine
python3 -c "from engine import OntologyEngine; e = OntologyEngine(); print(e.get_stats())"

# Test natural language queries
python3 -c "from natural_language import ask_ontology; print(ask_ontology('who works on icarus'))"

# CLI entry points
python3 -m ontology.engine stats
python3 -m ontology.engine query "what projects is socrates working on"
python3 -m ontology.engine export ~/Obsidian/Ontology
```

## Verified Query Patterns

| Pattern | Example | Result |
|---------|---------|--------|
| Projects involving | `what projects is socrates working on` | 📋 Icarus |
| Who works on | `who works on icarus` | 👥 Socrates, Daedalus, Wadsworth |
| Entity lookup | `who is wadsworth` | 📌 chief_of_staff, glm-5.1:cloud |
| List by type | `show all agents` | 📂 Wadsworth, Socrates, Daedalus |
| Relations | `relations of wadsworth` | 🔗 → Matt, → Icarus |
| Family | `who is in the hoffmann family` | 👨‍👩‍👧‍👦 Matt, Aundrea, Sully, Harper |
| Profile | `tell me about matt` | 📌 director, hoffmann family |

## Bootstrap Data (Pre-loaded)

**Board:**
- `person:matt` — Director
- `agent:wadsworth` — Chief of Staff (glm-5.1:cloud)
- `agent:socrates` — Backend Architect (kimi-k2.5:cloud)
- `agent:daedalus` — UX Architect (deepseek-v4:cloud)

**Family:**
- `person:aundrea` — Matt's spouse
- `person:sully` — Son, 1st grade
- `person:harper` — Daughter, pre-k

**Projects:**
- `project:icarus` — Phase 5, family assistant
- `project:costco_route` — Stable, shopping optimizer
- `project:ontology` — Building, knowledge graph

**Relations:**
- `serves`, `works_on`, `coordinates`, `child_of`, `spouse_of`

## Python API

```python
from ontology.engine import OntologyEngine, get_engine
from ontology.natural_language import ask_ontology

# Direct CRUD
engine = OntologyEngine()
engine.add_entity("concept:ghost_bug", "concept", "Ghost Bug", {"severity": "critical"})
engine.add_relation("project:icarus", "concept:ghost_bug", "affected_by")

# Natural language
result = ask_ontology("what projects is wadsworth working on")
# Returns: "📋 Projects involving wadsworth:
#   • Icarus (phase_5)
#   • Ontology (building)"

# Export to Obsidian
engine.export_to_obsidian(Path("~/Obsidian/Ontology"))
```

## Schema

### Entities
- `id` (PK): `type:name` format (e.g., `agent:wadsworth`)
- `type`: person, agent, project, event, document, skill, system, location, organization, concept
- `name`: Human-readable label
- `properties`: JSON flexible attributes
- `source`: Where we learned this (manual, system, inferred)
- `confidence`: 0.0-1.0 certainty
- `created_at`, `updated_at`: Timestamps

### Relations
- `from_id`, `to_id`, `relation_type` (composite PK)
- `properties`: JSON relation attributes
- `confidence`: 0.0-1.0
- `created_at`: Timestamp

### Observations
- Temporal facts about entities
- `entity_id`, `observation` (text), `observed_at`, `source`, `confidence`

## Obsidian Export

Generates Markdown files with wikilinks:
```markdown
# Wadsworth
**Type:** agent

## Properties
- role: chief_of_staff
- model: glm-5.1:cloud

## Relations
- → [[person:matt|Matt]] (serves)
- → [[project:icarus|Icarus]] (coordinates)
```

## Sovereign Stack Principles

- ✅ **No cloud dependencies** — SQLite only
- ✅ **No new graph DB** — Plain SQL, no Cypher/Gremlin
- ✅ **Natural language** — No query language to learn
- ✅ **Human-in-the-loop** — All modifications require explicit intent
- ✅ **Exportable** — Plain text, Obsidian-compatible
- ✅ **Clean-room** — Zero code from ClawHub skill

## Integration Points

**Wadsworth can use this for:**
- Cross-referencing projects and agents
- Family member lookups (e.g., "who needs to know about Sully's field trip?")
- Contextual awareness (e.g., "Socrates worked on Icarus → use backend patterns")
- Memory lineage (observations trace back to source)

**Future extensions:**
- Link to daily logs (`memory/YYYY-MM-DD.md`)
- Auto-extract entities from conversations
- Confidence decay for stale observations
- Temporal queries ("what was Socrates working on last month?")

## License

Same as OpenClaw — MIT or as specified by Director.

---
*Clean-room implementation. 1,100 lines. Zero dependencies. Sovereign by design.*