knowledge-os

A personal knowledge operating system: an Obsidian LLM-wiki maintained by Claude Code, with automated ingest, linting, memory consolidation, and a knowledge-graph query layer.

This is the architecture I run daily. The pattern comes from Andrej Karpathy's "LLM-legible wiki" idea — keep your knowledge in plain markdown, structured so an LLM agent can read, maintain, and answer from it — extended with agent-run maintenance routines so the wiki stays healthy without manual gardening.

                        ┌─────────────────────────────┐
   raw sources ───────► │  00-inbox/raw  (immutable)  │
   (docs, meetings,     └──────────────┬──────────────┘
    exports, URLs)                     │  /ingest (agent)
                                       ▼
                        ┌─────────────────────────────┐
                        │   curated wiki (01–07)      │◄──── lint routine
                        │   plain .md + frontmatter   │      (orphans, broken
                        │   [[wikilinks]] everywhere  │       links, conflicts)
                        └───────┬─────────────┬───────┘
                                │             │
                     hot.md ◄───┘             └───► graphify
                (~500-word cache,                (knowledge graph:
                 read first, 80% of               communities, god nodes,
                 questions answered)              path/explain queries)
                                ▲
                                │  dream routine (24h)
                        session transcripts
                        (corrections, decisions,
                         preferences → memory)

The pieces

1. The vault (vault-template/)

An Obsidian vault the agent treats as its long-term memory and single source of truth.

• Plain markdown + YAML frontmatter — every note has tags, type, date, status. No proprietary formats; any LLM can read the whole thing.
• Numbered lifecycle folders — 00-inbox/raw (immutable sources) → curated pages (01-daily … 06-people) → 07-archive (never delete).
• [[wikilinks]] everywhere — every entity, project, and concept links out. Links are how the agent navigates; a page without links is invisible.
• hot.md — the hot-context cache. A ~500-word compressed summary of everything that matters right now. The agent reads it first, every session; it answers ~80% of questions in one read instead of a multi-file crawl. Updated on every ingest that touches something important. This one file is the highest-leverage idea in the system: it converts "agent explores vault for 2 minutes" into "agent is grounded in 5 seconds."
• CLAUDE.md — the contract. Schema, conventions, operations (ingest / query / lint), and anti-patterns. The agent follows it; you audit it. See vault-template/CLAUDE.md.
• Contradiction discipline — new facts never overwrite old ones silently. The agent flags ⚠️ Conflict: inline and keeps both until resolved. An audit trail instead of silent drift.

2. graphify (skills/graphify/)

A Claude Code skill that turns any corpus — code, docs, papers, transcripts, images, videos — into a persistent, queryable knowledge graph.

• Extraction — entities and relationships pulled from every file, with an honest audit trail (every edge is STATED in a source or explicitly INFERRED).
• Community detection — the graph is clustered into topic communities; each gets a plain-language label, so a 2,000-node graph reads as ~15 themes.
• God nodes — the highest-degree hubs are ranked; they tell you what a corpus is actually about (frequently not what its README says).
• Query layer — query (BFS, broad context), path A B (shortest path between two concepts), explain X (what is this node and what touches it), with token budgets so answers stay small.
• Outputs — interactive HTML graph, GraphRAG-ready JSON, a plain-language GRAPH_REPORT.md, optional Obsidian vault / Neo4j / GraphML / SVG exports, an MCP stdio server for agent access, and a --watch mode that rebuilds on file changes.

Why it matters for the wiki: the vault answers "what do I know about X"; graphify answers "how is everything connected, and what's central" — the structural questions plain search can't touch.

3. Routines (routines/)

Maintenance the agent runs so the human doesn't have to.

• dream — nightly memory consolidation. A Stop-hook fires every 24h; the agent scans recent session transcripts for corrections, decisions, and preferences, and merges the durable ones into persistent memory. Named for what sleep does to human memory. Without it, every hard-won correction dies with its session.
• lint — wiki health check: orphan pages, broken wikilinks, stale claims, index drift, unresolved ⚠️ Conflict: flags.
• handoff — end-of-session state dump into a session-memory note with an explicit resume protocol, so the next session (or a context-cleared one) restores in one read.

4. The agent front-end (pattern)

The wiki and graph are the memory; a small agent layer is the interface. In my setup a Telegram agent (Hermes) fronts the system, routing requests through a capability registry — a single JSON index of everything the system can do, spanning three tiers:

• Tier 1 — chat agent (Telegram): quick questions, daily briefs, anything answerable from hot.md + registry lookups.
• Tier 2 — Claude Code sessions: real work — ingest, builds, analysis — with the full vault as context.
• Tier 3 — scheduled workers: cron/LaunchAgent jobs (nightly consolidation, digests, monitors) that write results back into the wiki.

The registry is what keeps three tiers coherent: every capability is registered once with a label and an owner tier, so "can the system do X, and where" is one lookup (~200 entries in my instance). The registry file itself is trivial — the discipline of registering capabilities is the feature. Not shipped in this template (it's wiring, not architecture); the pattern is described here because it's the piece that turns a knowledge base into an operating system.

Design principles

1. Agent-legible beats human-pretty. Consistent frontmatter and links beat elaborate formatting. The reader is usually a model.
2. Compress at the top, detail at the leaves. hot.md → index.md → pages. Every query starts cheap and drills only as needed.
3. Immutable sources, curated wiki. Raw inputs are never edited; the wiki is derived. You can always re-derive.
4. Never delete, always archive. Storage is free; lost context isn't.
5. Conflicts are data. Contradictions get flagged, not resolved by whichever write came last.
6. Maintenance must be autonomous. A knowledge system that depends on human discipline decays. Routines run on hooks, not willpower.

Using this template

1. Copy vault-template/ as your Obsidian vault; edit CLAUDE.md to your domains.
2. Point Claude Code at the vault (project instructions or additionalDirectories).
3. Install the graphify skill (skills/graphify/ → ~/.claude/skills/graphify/).
4. Set up the routines (each doc describes its hook wiring).
5. Feed the inbox; let the agent do the bookkeeping.

All example content in this repo is fictional. The pattern is real — this is the exact architecture I run — but the data stays private, which is rather the point of a personal knowledge OS.