2context extracts architectural decisions, conventions, and patterns from your git history and writes them as plain Markdown files. Coding agents like Claude Code read those files directly the same way they read any other file in your repo. No MCP server, no daemon, no API.
or run without installing: npx 2context init
// not just a docs folder
Markdown for agent context is not new. What is new is what ends up in those files, how they stay organized, and how the agent picks them up without your prompting.
Intent extracted from commits. The why behind decisions (why this DB, why that boundary) gets reconstructed from diffs and commit messages, including reasoning that never made it into a doc anyone bothered to write.
Self-organizing graph. As items pile up, LLM clustering splits overfull category folders into subfolders and merges underfull ones. The structure stays navigable instead of decaying into a flat dump.
Auto-discovered by the agent. A ## Knowledge Context block is written into CLAUDE.md / AGENTS.md instructing the agent to read the index before any task. No prompt engineering required.
Validated, not just appended. Items are tied to source provenance (commits, files). When the underlying code disappears, 2context validate drops the stale item so the graph does not drift from reality.
// how it works
Run 2context ingest after merges (or in CI) to keep the graph current.
State is tracked per source, so each run only processes commits added since the last cursor.
Reads commits since the last cursor (full history on first run). Skips merges, dependency bumps, and formatting-only changes.
An LLM groups related commits into feature units, then reads the diffs and extracts knowledge items with category, summary, content, and source provenance.
Items are written to co-located KNOWLEDGE.md files next to the code they describe, and to the central graph at .2context/graph/{category}/.
Overfull category folders get split into subcategories via LLM clustering. Underfull folders get merged. 2context validate drops items whose source has disappeared.
A ## Knowledge Context section is written into CLAUDE.md or AGENTS.md instructing the agent to read .2context/KNOWLEDGE_GRAPH.md before starting any task.
// output
Two output planes: co-located files next to the code they describe, and a central graph
indexed by a single entry point at .2context/KNOWLEDGE_GRAPH.md.
Module boundaries, data flow, layer responsibilities.
Naming, file organization, error handling, import patterns.
Why this library, why not that approach, with context intact.
Recurring implementation approaches across the codebase.
// sources
The current build ships with one adapter: git-commits.
The pipeline is built around a generic adapter interface, so additional sources can feed
the same graph without changing how it is consumed.
Reads commits, groups them into feature units, extracts items with traceable source refs (commit SHA, files touched).
Capture review discussions, rejected approaches, and the decisions that landed in PR descriptions.
Pull existing architecture docs, ADRs, and issue threads into the same graph the agent already reads.
The adapter contract is small. Anything that can produce material units with provenance can plug in.
// llm providers
Configure via env vars or the interactive wizard on first run. Keys stored in ~/.2context/keys.json (chmod 600).
// get started
Works in any git repository. Node.js ≥ 22 required.
Full docs on GitHub · npm · report an issue