A freshly installed toolkit knows engineering; it doesn’t know your project. The knowledge system is how that changes — and why a calibrated project gets fixes that match its conventions and QA that understands its domain rules. It has three parts: what /calibrate seeds, the knowledge base that accumulates over time, and the graph that makes it queryable.
Calibration’s scanner deep-reads the project — platform, architecture patterns, coding conventions, testing patterns, domain model, integrations, environments — and writes two things:
.claude/project-profile.md — the synthesized profile: architecture, conventions, domain model. This is the file agents read at runtime; skills like /sre and /pr consult it instead of re-discovering the project every session..claude/knowledge/ — the seeded knowledge base, populated by a dedicated knowledge agent, including shared/best-practices.md extracted from your codebase (or generated for your stack).Everything is plain Markdown in your repo. You can read it, edit it, and review changes to it like any other file — and uninstalling the toolkit deliberately leaves it in place, because it’s yours.
The shared core lives at .claude/knowledge/shared/:
| File | Holds | Read by |
|---|---|---|
conventions.md |
Coding rules, often learned from corrections | Anything writing code |
domain.md |
Business rules that aren’t visible in the code | Domain decisions, QA |
vocabulary.md |
What your team calls things | Everything — naming consistency |
patterns.md |
Architecture patterns to follow when adding code | Builders and planners |
best-practices.md |
Calibration’s extracted/generated practices | Builders and reviewers |
decisions.md |
Recorded decisions (e.g. infra choices from /sre) |
Future decisions |
Around it, workflows maintain their own memory: skills append what they learn to .claude/knowledge/skills/<skill>.md (PR patterns, CI-failure patterns, incident classification accuracy), agents to .claude/knowledge/agents/<agent>.md, and the QA system keeps a parallel base at .claude/qa-knowledge/ (bug patterns, coverage gaps, flaky tests, incident reports). The knowledge base isn’t a snapshot — it compounds: every /fix, /ci-fix, /incident, and /qa run can write back, which is why diagnosis gets faster on a project the toolkit has worked in for a while.
Loading every knowledge file in full on every task would be slow and expensive. Instead, the toolkit builds a knowledge graph — a ranked index of the knowledge base — at .claude/knowledge/graph/:
Workflows that query it include /fix, /planning, /implementation-plan, /implement, and /qa; /goal’s scout phase reads the knowledge base before scanning the codebase, and /incident checks it for similar past incidents during diagnosis. Planning workflows also write back — /planning records a decision entry in the graph, and /implementation-plan writes architecture decisions to shared/ and the graph.
The graph is also renderable: /kb-architecture-diagram draws your knowledge base as an architecture diagram, and a hook refreshes it when the KB changes.
The effect to internalize: project knowledge is externalized into files, not held in a session’s memory. Sessions end and context windows compact, but the knowledge base persists — so the next session, the next skill, and the next teammate’s machine all start from the same accumulated understanding. Calibration seeds it, workflows grow it, and the graph keeps retrieval cheap as it grows.