Use cases
Three small Markdown records kept beside the work: the current state, the decisions that constrain what comes next, and the learnings that were verified. Two very different kinds of project, one record — the familiar repository, and everything else a group builds together.
The familiar case: a software repository where AI coding agents do real work across many sessions, weeks apart, in different tools, on different machines.
A session ends halfway through splitting the auth module. Days later the next agent — often a different agent entirely — opens the current-state record and finds what was decided, what already landed, and what is still open. It does not re-derive the plan from a diff, and it does not start a fourth parallel approach.
Why short-lived JWTs rather than server-side sessions. Which conventions are settled and not up for reopening. Written down as decisions with the reasoning attached, so a later agent does not silently reverse a choice it never saw being made.
A root cause the code does not make obvious. An approach that was tried, failed, and would fail the same way again. Verified learnings are how that loop stops repeating every few weeks at the cost of another afternoon.
Claude Code today, Codex tomorrow, Cursor on the laptop. Because the records are committed alongside the code, the context travels with the project instead of living in one vendor's memory store.
Records go stale quietly, and a stale record is worse than none. A read-only doctor is what keeps the difference visible.
The evidence anchor. A decision pins its justification to a path at a commit, so a later session can check whether the reason still holds.
A decision pins its justification to path/to/file@commit. The doctor reports evidence-drift when that file has changed since — meaning the justification may no longer hold, and the decision is worth a second look before anyone builds on it.
The managed instruction block, a harness pointer or a working hook must still deliver the protocol into a session. no-delivery-path is an error, because perfect files that nothing ever loads otherwise report healthy.
Project Context works for any project a group of people and agents work on together, whose materials live in one folder they can all reach. Supported project types are software, document, research, writing, and mixed.
Best suited to repo-bound collaborative work, where version control makes shared context easy to review and evolve.
It also works for any project whose working materials are organized in one folder that people and AI agents can access consistently.
Nothing about them is specific to code. A literature review, a manuscript and a client engagement all have a current state, decisions that constrain what comes next, and learnings that were verified rather than assumed.
current state
Where the project actually stands today, what is in flight, and what is blocked — the first thing the next person or agent reads.
decisions that constrain future work
The choices already made and the reasoning behind them, so later work builds on them instead of quietly undoing them.
verified learnings
What was tried and what it actually taught you — kept separate from what everyone merely believes to be true.
Same records, same folder, no repository of source files in sight.
Screening criteria were settled in March. The dataset was swapped in May for a reason nobody wrote down. Three different agents have since summarised the same twenty papers. The decision record holds why the inclusion criteria are what they are; the learnings record holds which extraction pass produced unusable output — so the next pass starts where the last one stopped, not where the last one started.
Long-form work is mostly continuity: what the reader already knows by chapter nine, which voice was agreed for the second act, the terminology call that has to hold across four hundred pages. Editorial decisions live as decisions with their reasoning, rather than as somebody's memory of a conversation in a chat window nobody can find.
Deliverables, constraints and the commitments made in week two are exactly the things that walk out of the door with whoever leaves. Held as records in the engagement folder, they survive a handover: the analyst who joins in month five, and the agent drafting the next deck, can both see what was promised and on what basis.
An operations or policy handbook edited by people and agents together drifts quietly. A rule changes, the reason never gets recorded, and six months later nobody can say whether it still applies. The decision record carries the reasoning; the current-state record says which version is in force today and what is still under review.
Version control is the best case, not a prerequisite. Without it, the tooling falls back to file-modification times to detect that work has landed since the context was last updated.
Without git you lose the commit-anchored evidence trail and the drift detection that depends on it. The records still work. The verification is weaker.
It works the same whether that folder holds source files, a manuscript or a client engagement.
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context init --target . --apply
Clarity comes with context.