accreta

A knowledge base your AI agent writes, maintains, and is held accountable for.

accretion (n.) — growth by the gradual accumulation of matter.

[!NOTE] Status: v0.1.0. All six roadmap phases are complete and the pipeline runs end to end — see the worked example. The API is not yet stable, and two deliberately deferred pieces are listed in the roadmap.

---

The idea

Most attempts to give an AI agent knowledge of a large system reach for RAG: embed everything, retrieve chunks at query time, hope the model assembles them correctly. The context is rebuilt from scratch on every question, and nothing learned in one session survives into the next.

accreta takes the other path, following Karpathy's LLM wiki pattern: the agent compiles knowledge into a wiki of interlinked markdown pages, once, and then keeps it current. Cross-references, synthesis, and contradictions are already written down. The knowledge base is a compounding artifact, not a lookup index.

That shift buys three things RAG cannot easily provide:

• Provenance. Every non-trivial claim cites the source it came from, down to the line range and revision. A page without citations is a page under suspicion.
• Drift detection. Each page records the source revision it was last verified against. When a source moves, accreta tells you which pages are now suspect — the thing documentation never does on its own.
• Refusal to over-synthesize. When the sources disagree, the agent is instructed to record the contradiction rather than silently pick a winner.

What it is, concretely

A knowledge base is a directory of markdown files with YAML frontmatter and [[wikilinks]]. accreta gives you the machinery around it:

• an indexer — SQLite FTS5 full-text index plus a link graph across pages;
• an MCP server — so any agent (Claude Code, Cursor, or anything speaking MCP) can search, fetch pages, resolve canonical definitions, and run impact analysis;
• source adapters — a source is anything with a revision and a way to detect change. Git repositories are one kind. Directories of documents are another;
• a CLI — init, reindex, lint, drift, search, show, consumers, canonical;
• a constitution — the operating rules the agent follows when writing pages, versioned as a template rather than pasted into a chat.

sources (git · files · …) ──► agent writes pages ──► index (FTS5 + links)
        ▲                          with provenance             │
        └───────── drift: which pages did this change invalidate?
                                                               ▼
                                                    MCP server · CLI

Not just code

accreta was extracted from a system that documented a 17-repository backend, so code is the best-tested case — but the core knows nothing about code. It knows about sources that have a revision and can report what changed.

examples/climate/ demonstrates the same machinery over scientific reports: no symbols, no call graph, no imports. Ten pages, two sources, lint clean and drift verifying — including a contradiction page that records a factor-of-three disagreement between two sources and refuses to resolve it.

The vocabulary there is source, concept, finding, contradiction, synthesis. No module, no api, no endpoint — page types are configuration, not code (ADR-0003).

Roadmap

Phase	What	Status
1	Core: indexer, frontmatter, link graph	done
2	SourceAdapter interface, git and fs adapters	done
3	MCP server and CLI	done
4	Hybrid search — measured, and decided against	done
5	Constitution templates and setup skill	done
6	Demo knowledge base, docs, v0.1.0	done

Two pieces are deferred rather than built, each with a reason and an issue: hosted deployment auth and the sync loop, and skill distribution. Both serve a deployment story that does not exist yet, and building them now would encode guesses that become load-bearing before anyone has tested them. Skill distribution waited specifically on there being a package to install from; that now exists, so the guessing is over and the issue can proceed on evidence.

Progress is tracked on the project board, one epic per phase.

Install

bun add -g accreta

accreta runs on Bun, not Node. It ships as TypeScript and uses bun:sqlite, so there is no build step and no Node build to fall back to. The engines field says so, but neither npm nor Bun enforces it: installed under Node, the CLI fails on the first import rather than with a useful message. This is a real limitation, not an oversight — see ADR-0005.

Try it

bun install
cd examples/climate
bun run ../../packages/cli/src/main.ts reindex   # 10 pages, 27 links
bun run ../../packages/cli/src/main.ts lint      # clean
bun run ../../packages/cli/src/main.ts drift     # up to date, both sources
bun run ../../packages/cli/src/main.ts canonical "ECS"

To start your own:

accreta init --preset research    # or codebase, or neither

Design decisions

Four ADRs in docs/adr/:

• 0001 — search is lexical, and semantic search is not built. The benchmark said 85% recall@1 without it. It also found a bug in our own index first: aliases were not being indexed, which cost 15 points and looked exactly like evidence that lexical search cannot handle synonyms.
• 0002 — a source is four methods, and changedSince() must be able to say I cannot tell.
• 0003 — page types and link fields are configuration; the schema follows the same rule.
• 0004 — markdown is the source of truth and the index is disposable.

Further reading: architecture, writing an adapter.

Contributing

Contributions are welcome, with one request: open an issue before a pull request. It takes a minute and it protects you from building something that does not fit the direction. New source adapters are the most useful contribution and have their own issue template.

See CONTRIBUTING.md.

License

MIT — see LICENSE.