Core Concepts

This page is the precise reference for the ideas the rest of the docs build on. If you want the persuasive tour instead, start with the Overview; if you want to start using it, see the Quickstart.

Three layers

Open Knowledge is three layers working together: a surface you edit, an engine that keeps it consistent, and the files underneath.

All three layers operate on the same files. You can edit through the editor, an agent can edit through the knowledge engine's MCP tools, and you can always drop down to any text editor and change the markdown by hand. Nothing locks you out.

Because the knowledge engine is exposed over MCP, it is agent-agnostic. Bring Claude Code, Cursor, Codex, Gemini, or any MCP-capable client, and any model you have access to.

The file system is the database

The third layer is the content itself. Open Knowledge has no database dependency. Your knowledge base is plain markdown files in your own project directory, and the only persistence layer is the file system, version-controlled by git.

This means:

• No lock-in. Your knowledge is portable markdown you can read, grep, diff, and commit with ordinary tools.
• Almost nothing to install. The recommended path is the macOS app; there is no separate database or service to run.
• The engine is a management layer, not a gatekeeper. It maintains consistency when you go through it, but editing the raw files yourself is always allowed.

The set of files the engine treats as your knowledge base is the configured content directory. See Configuration for where that and other settings live.

Links and backlinks

Internal cross-references are written with standard markdown links: [text](./relative/path.md) or [text](/absolute/from/content-root.md). Whenever document A links to document B, Open Knowledge automatically records the inverse on B: a backlink from B back to A.

You never write backlinks by hand. They are computed from the links you already write, and together they form the link graph: the network of relationships across your knowledge base.

The well-connected knowledge base

"Well-connected" is not a vibe; it has concrete substance:

A well-connected knowledge base = backlinks + the link-graph tools (dead / orphans / hubs / suggest) + closed-loop grounding.

Backlinks

The automatic inverse relationships described above. They turn a pile of files into a navigable graph.

The link-graph tools

The knowledge engine exposes a links tool whose kind selects a view of the graph. Four of these views are how you keep the graph healthy:

Agents use these to repair and densify the graph as they work, instead of letting it rot.

Closed-loop grounding

Every factual claim should trace back to a source inside the knowledge base. External material is pulled in and cited locally rather than linked off to the open web, so the knowledge base stays self-contained and auditable. This is the backbone of the source-grounded workflows: see Karpathy's LLM wiki workflow and the Entity vault (GBrain-compatible) workflow.

Attribution and collaboration

Every change made through Open Knowledge is tracked, with attribution to whoever made it: a human author or a specific AI agent. The change history is persisted in the file system with no dependency beyond git.

That gives you:

• A changelog of every edit across the knowledge base.
• Point-in-time history. Revert to any earlier state.
• Per-author views. See exactly what one human or one agent changed.

Because humans and agents edit the same files through the same tracked layer, collaboration is a first-class property of the system rather than something bolted on.