selmakcby/claude-obsidian-kit/llm-wiki

LLM-Wiki

The shared brain pattern for AI agents. Turn ephemeral agent conversations into persistent, searchable, human-editable knowledge stored as markdown files in an Obsidian vault.

Unlike RAG systems that rediscover context on every query, llm-wiki accumulates — the agent reads new sources, integrates them with existing knowledge, updates entity pages, flags contradictions, and maintains cross-references.

Three operations (and which agent runs each)

1. INGEST — Absorb new knowledge (runs on scribe, haiku)

When: A new source arrives (session transcript, decision, doc, finding).

Flow:

source  →  scribe (haiku) → format + write summary note
                          → update index (one-line append)
                          → cross-link related pages

Why scribe: running a cheap haiku-backed writer is ~10× cheaper than having the thinking agent (planner/builder) format its own output. Separate thinking from writing.

See [[ingest]] for detailed protocol.

2. QUERY — Retrieve & synthesize (runs on archivist, sonnet)

When: Someone asks a factual question about the project.

Flow:

question  →  archivist (sonnet) → read index (1 file) → grep relevant
                                → read 2-5 notes → synthesize answer
                                → (if useful) recommend refiling

Token rule: never load more than 5 notes per QUERY. If you need more, the question is too broad.

See [[query]] for detailed protocol.

3. LINT — Vault health (runs on archivist, sonnet)

When: Periodic check (weekly) or on-demand.

Flow:

full vault scan → orphans + broken links + stale notes + missing concepts
                → severity-sorted report with fix suggestions

LINT is read-only — flags issues, doesn't fix them. Human decides.

See [[lint]] for detailed protocol.

Vault structure (standard)

vault/
├── index.md              ← entry point, links to all top-level concepts
├── _schema/
│   ├── template.md       ← frontmatter template for new notes
│   └── conventions.md    ← naming, linking, tagging rules
│
├── architecture/         ← how it's built
├── decisions/            ← why we chose X over Y (dated)
├── design/               ← UI decisions, component briefs
├── entities/             ← tools, services, people
├── concepts/             ← cross-cutting ideas
└── sessions/             ← dated session summaries

Routing rules (where does a note go?)

Frontmatter (required on every note)

---
type: decision | session | entity | concept | architecture | design
date: YYYY-MM-DD
tags: [auth, payments, ...]
links: [[other-note]]
status: draft | accepted | deprecated
---

Golden rules

• Accumulate, don't replace. New info merges with existing. Never silently delete.
• Atomic notes. One idea per note. 200-400 lines ideal, 800 max.
• Link aggressively. 200 well-linked notes > 2000 disconnected ones.
• Human-readable. Write for future-you. Not JSON, not dense summaries — readable markdown.
• Shortest path links. [[stripe]] not [[entities/stripe]] — Obsidian resolves.
• Date everything. Frontmatter date mandatory. Decisions/sessions also in filename.
• Status is a decision log. Old decisions don't get deleted, they get status: deprecated.

When to skip the vault

• Exploratory chat (not a decision yet)
• Sensitive data (PII, secrets, credentials)
• Trivial statements ("ok", "done")
• Duplicates — update existing note instead

See also

• ingest.md — INGEST protocol details
• query.md — QUERY protocol details
• lint.md — LINT protocol details