Local-First AI Knowledge Base (Obsidian + Coding Agent)

A template for building a local-first, AI-maintained knowledge base on top of an Obsidian vault, driven by a coding agent (Claude Code, Codex, Cursor, etc.).

You give the agent raw material and questions; the agent compiles that raw material into a queryable, reusable, evolving wiki — with privacy gates, link/quality lint, and a safe text-only path to a shared Git repo.

This repo ships structure, rules, automation scripts, and fictional examples only. It contains no real business knowledge, customer data, or secrets. Fork it and grow your own vault on top.

Why this exists

Obsidian backlinks are great for a single author but do not translate directly into a team-facing or shareable format. The core idea:

Keep one local canonical layer (full backlinks + frontmatter governance), and compile safe published copies out of it. Never publish the local master directly.

Core model

raw/  ──▶  agent: ingest / query / lint / refactor  ──▶  wiki/ (canonical)
                                                            │
                                          ┌─────────────────┴───────────────┐
                                          ▼                                  ▼
                              Git private repo (text-only)        team-safe / open export

Five page types carry the whole system:

type	answers
source	what does this raw material say
concept	what is this idea, how to reuse
entity	who/what is this object
playbook	how do I act in this situation
summary	what's the conclusion so far

Layout

.
├── AGENTS.md                 # single rule entrypoint the agent reads
├── wiki/
│   ├── index.md              # query entrypoint (every page linked here)
│   ├── hot.md                # recent-context cache, read first for low token cost
│   ├── _example-domain/      # fictional example pages
│   └── kb-ops/framework.md   # the framework master (this template's brain)
├── domains/projects/         # leaf projects, each with README.md + AGENTS.md
├── templates/                # frontmatter templates per page type
├── tools/wiki/               # query, lint, safety audit, hot-cache, manifest
├── docs/                     # architecture, privacy, Obsidian setup, quickstart
└── .gitignore                # text-first: raw/binaries/secrets never tracked

Quickstart

git clone <your-fork> my-kb && cd my-kb
python3 -m venv .venv && source .venv/bin/activate   # stdlib-only tools, venv optional
python3 tools/wiki/lint_links.py --summary           # health check
python3 tools/wiki/query.py "example"                # local retrieval
python3 tools/wiki/init_project.py "team-learning/onboarding" --title "Onboarding"

Then open the folder as an Obsidian vault and point your coding agent at AGENTS.md.

Full steps: docs/QUICKSTART.md · Architecture: docs/ARCHITECTURE.md · Privacy gates: docs/PRIVACY-AND-SECURITY.md · Obsidian: docs/OBSIDIAN-SETUP.md

License

MIT — see LICENSE.