Using coding-agent to Build a Local-First Knowledge Base

The first thing to understand about personal-knowledge-base is that it is not a note app with a hidden storage layer underneath. It is a directory of markdown files with several transports on top. The repo states the invariant directly: if a feature breaks cat, grep, git, or rsync, the feature is wrong.

That rule shapes the architecture immediately. Notes live in kb/. src/core/ is the only layer that touches the filesystem. The Next.js UI, the kb CLI, and the MCP server are all thin transports over the same core library. Optional S3 sync follows the same model instead of replacing it.

Once you read the repo through that lens, the semantic-search slice makes sense. The embeddings sidecar lives in kb/.kb-index/embeddings.jsonl as generated state. search.ts and semanticIndex.ts extend the core search path, but they do not change what counts as the source of truth. search_notes over MCP keeps the same shape. kb reindex exists because rebuilding derived state is a maintenance verb, not a magic background behavior.

That separation matters more than the model choice. The useful result is not that the KB now has AI search. The useful result is that the repo can add a semantic layer without turning the directory into a sync target for a hidden system.

The second story is how that feature was built. This repo used the earlier coding-agent plugin, and the evidence is local. .coding-agent/spec.md locked the important decisions up front: local embeddings, .kb-index/ as a JSONL sidecar, hybrid ranking, no new MCP tool, and no violation of the filesystem-first rule. That is the value of the spec file here. It constrains the slice before code starts.

plan.md then decomposed the work into concrete modules: probe the model dependency, create embeddings.ts, create semanticIndex.ts, wire fs.ts hooks without reversing the dependency direction, extend search.ts, add kb reindex, and add tests. progress.md recorded actual timings like cold model load, warm load, sidecar size, and reindex speed on the real corpus. review.md checked the shipped code against acceptance criteria instead of just declaring the result good enough.

The repo also carries the session state that made the work resumable: .coding-agent/CURRENT, agent-log.txt, research/transformers-js-probe.md, and feature-scoped folders under .coding-agent/features/. Those files are not there to imitate discipline. They are there so the next session can see what feature is active, which agents were dispatched, what got measured, and what still looks suspect.

That same pattern is reinforced in AGENTS.md. The file does not just say "use the plugin." It encodes repo-specific contracts: src/core/ is the only filesystem layer, no new dependencies without approval, the CLI and MCP do not read .env, .kb-index/ is generated state, and verification means pnpm typecheck, pnpm build, pnpm kb search, pnpm kb tree, and pnpm mcp. That is exactly the kind of instruction file I trust: concrete boundaries plus concrete checks.

The strongest part, though, is the dogfooding loop. AGENTS.md says the repo's own kb CLI is how agents should navigate the user's KB during any work session. Before starting, the agent is supposed to run kb info, kb ls, kb search, follow links with kb cat and kb backlinks, and read meta/ notes for prior context. After shipping, the agent is supposed to write a new session note back into the KB and log rough edges to the improvement backlog.

That makes the project more interesting than a knowledge base with MCP. The product is also the working memory surface used during development. The agent is not only building the KB. It is using the KB to recover context, check prior conclusions, and leave a better starting point for the next session.

The learnings file is where this gets honest. After the semantic-search work and the later dogfood pass, learnings.md does not only talk about the KB. It talks about the plugin's own failure modes: classification thresholds that were too aggressive, too much ceremony for touch-up work, AGENTS conventions drifting from the actual codebase, reflection being optional instead of enforced, and the irony that the orchestrator did not follow the repo's own dogfooding rule.

That is useful evidence. The system is not only producing code. It is surfacing where its own workflow is wrong.

That is why I think this repo is a better coding-agent example than a toy app. First, the KB architecture is clear: markdown in kb/, shared core in src/core/, thin UI / CLI / MCP transports, derived search state in .kb-index/. Second, the coding-agent workflow is explicit: spec, plan, progress, review, learnings, and feature folders live in .coding-agent/. Third, the repo is dogfooded: agents use kb to work on the KB, and the resulting learnings feed back into the plugin. That is a much stronger story than "the agent shipped a feature." It shows how a repo can stay inspectable while both the product and the workflow get smarter.