Project Context — MonoMind

01

What Project Context actually is

A handful of small Markdown files that live in the project folder, next to the work. Between them they hold where things stand right now, the decisions that constrain what comes next, and the learnings that have been verified. The agents doing the work write and maintain them. The next agent — or the next person — reads them first.

the files

Small Markdown, in the folder

No database, no service, no vendor memory store. A few tracked files sit beside the work and open in any editor.

what they hold

State, decisions, learnings

Where the project stands today. The decisions that bind what comes next. The findings that were verified, so nobody pays for them twice.

who keeps it

Maintained by the agents doing the work

Updating the record is part of finishing a piece of work, not a report filed afterwards — and it is the first thing the next session reads.

Code
Documents
Research
Writing
Mixed
any collaborative project an agent works on

Not only software, and not only GitHub. Software, document, research, writing and mixed projects all keep the same kind of record.

It suits repo-bound work best, where version control makes shared context easy to review. But any project whose working materials live in one folder that people and agents can reach consistently will do.

Git is not required. Without it, the tooling falls back to file-modification times.

02

What actually gets written down

Not a transcript, and not a summary of the chat. Each file answers one question a returning session really asks: where does this stand, what is already settled, and what did we learn the expensive way.

work stops for the day
the three files are brought up to date
the next session opens with the state in hand

NOW.md markdown

Current Project State

Last reviewed: 2026-08-30

Snapshot

Area	Current state	Evidence
Auth	Session cookies replaced by short-lived JWTs	D-014

Active work

Initiative	Status	Next action
Rate limiting	in-progress	Decide per-tenant vs per-key before the gateway merge

Blockers

Staging Redis is single-node; the limiter needs a cluster before load tests.

what the next session reads first

DECISIONS.md markdown

D-014: Short-lived JWTs over session cookies

Status: accepted

Date: 2026-08-24

Statement: API auth uses 15-minute JWTs with refresh, not server-side sessions.

Rationale: The mobile client cannot share a cookie jar with the web app.

Consequences: Every service needs clock sync; revocation is now a denylist.

Evidence: src/auth/jwt.py@a1b2c3d

what constrains the next agent

LEARNINGS.md markdown

L-007: Redis keyspace events drop silently under memory pressure

Scope: rate limiting, staging

Evidence: infra/redis.conf@3f9a1c2

Action: Do not rely on keyspace notifications to expire limiter buckets; poll the sorted set instead.

what nobody should have to discover twice

src/auth/jwt.py@a1b2c3d

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.

The distinction

Project Context records what the code cannot say — the decisions, the learnings, the current handoff.

A generated wiki regenerates what the code does say.

They compose: Project Context is the authority layer; a generated wiki is an optional derived view.

authority layer Project Context

Decisions, learnings, the current handoff — written by hand or by an agent, versioned with the code.

derived view · optional A generated wiki

Regenerates what the code already says. Useful, replaceable, and not the source of truth.

03

One command, or one prompt

uvx

Runs the CLI straight from the repo. No clone, no virtualenv. Swap --apply for --dry-run to print the plan first.

uvx --from git+https://github.com/monomind-ai-lab/project-context project-context init --target . --apply

pipx

Keeps init, inspect, review and doctor on your path.

pipx install git+https://github.com/monomind-ai-lab/project-context

prompt

Paste one prompt into any agent that can read and edit the folder. Zero tooling.

no CLI, no install — the agent writes the files itself

zero runtime dependencies · stdlib Python 3.10+
a stock install lands 13 files
the installer is never copied into your repo

04

It comes with you

Claude Code
Codex
Cursor
any agent that reads a folder

Your context lives in your git history, not a vendor's memory store.

Switch tools or machines and it comes with you.

05

How it stays true

A read-only doctor checks three things.

The documents hold up

Required files, version, NOW.md freshness, duplicate IDs, broken links.

Evidence anchors

path@commit pins a citation. evidence-drift warns when the cited file changed since — meaning the justification may no longer hold.

Reachability

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 nothing ever loads otherwise report healthy.

06

Add-ons, only where they earn it

Three independent open-source tools can sit alongside the record. Project Context does not just list them: it inspects the project, recommends only what fits, and installs or configures nothing until you have said yes.

it inspects the project
it recommends only what fits
nothing lands until you opt in

Per tool, the initializer separates two states that look identical from the outside: merely available on your PATH, and actually configured for this repository. Something already installed but unconfigured gets an offer to configure it, not a pointless reinstall. It asks only about unconfigured tools that match the confirmed project type and a need it has actually observed — and it installs only after an explicit answer.

Tool	What it is	When it fits	Relation to Project Context
GitNexus	Code symbols, their relationships, impact analysis and execution flows.	Source that needs structural or impact analysis. Suppressed for writing projects; on mixed ones it is scoped to a meaningful code subtree.	A derived read of the code. The decisions about that code still live in the tracked Markdown.
Graphify	Relationships across code, documents, research artifacts and media.	When the useful corpus reaches past code — a substantial interlinked document set, cross-source research and evidence, or a large relational manuscript or story world.	A derived index over your material. Rebuildable, and never the thing being cited.
OpenWiki	Ongoing generated documentation and navigation for stable projects.	Stable, complex projects with a real audience for derived navigation. Deferred while claims or structure are still moving; suppressed for writing projects.	Regenerated from what already exists — including the record it is generated against.

What gets offered, by project type

Code
GitNexus when the source needs structural or impact analysis. OpenWiki only for stable, complex projects with a real audience for derived navigation. Graphify when the useful corpus extends beyond code.
Documents
Graphify for a substantial interlinked corpus. OpenWiki only when collaborators need a maintained browse layer.
Research
Graphify for cross-source, data and evidence relationships. OpenWiki is deferred until claims and structure are stable.
Writing
GitNexus and OpenWiki are suppressed. Graphify only for a large relational manuscript or story world.
Mixed
GitNexus, scoped to a meaningful code subtree.
General
Nothing is offered until inspection finds a concrete need — the same answer while the type is still uncertain.

Project Context stays the authority. The tracked Markdown is what the project is committed to; these three are optional derived systems built from it. None of them becomes the source of truth, and the record works fully with none of them installed.

independent open-source tools · optional · installed or configured only after you opt in

Weeks away should never mean rebuilding the project from stale chats.