Project Context — MonoMind

01

What Project Context actually is

A handful of small Markdown records that live beside one project. They hold current state, constraining decisions, and verified learnings. The agents doing the work maintain them; the next agent — or person — reads them first. An organisation running several projects can add a private Project Hub; a single repository needs nothing but this.

the files

Small Markdown, under your control

No database, server, or vendor memory store. Keep the files with one project, or run a private Git-backed Project Hub across projects and open either in Obsidian or 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.

An optional private Project Hub authors the tier that applies across all your repositories — guardrails, workflows, the epic each project serves — and pushes it down. A repository with no Hub simply has no global/ and no blueprint/, and everything on this page still works.

Git is optional for a project record and the transport for a Hub push, which lands on a hub-sync branch as a pull request you review. Either way, Markdown stays canonical and no database or server is required.

How the two products split, and what a push actually sends → Project Hub

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

Decision: 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 . --install-skills --apply

pipx

Keeps all nine subcommands on your path: init, update, capture, inspect, context, onboard, review, consolidate and doctor.

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 18 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 runs eight families of checks and writes nothing. Some are silent on a repository that has no Hub — a standalone install is a complete product, not a broken one.

Core files, marker and version

Every required file is present and the marker parses. A schema this doctor does not read is an error; a marker another product wrote is named rather than compared; an installed version behind the available one asks for project-context update.

Record conformance

Each detail record carries the six required frontmatter keys, a status drawn from its own kind's vocabulary, and references whose shape matches the one reference grammar — validated by shape, never by resolving them.

Freshness, duplicate IDs, broken links

A Last reviewed: date older than the threshold, one record ID claimed by two files, and a relative link that resolves to nothing.

Evidence anchors

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

The pushed set is still what was sent

A pushed file stays clean Markdown, so the only evidence it is unaltered is the digest the push recorded in the marker. A local edit is reported as an error naming the Hub, because that is where the change belongs — editing it back here would only be undone by the next sync.

PLAN.md against the epic

A plan item that serves no item in blueprint/EPIC.md is an error: effort is going somewhere nobody asked for. An epic item no plan item serves is only a warning, because an epic legitimately runs ahead of the current milestone.

Legacy Context Hub artefacts

The superseded context-hub/1 schema string and its old scaffold are still recognised and reported, so a half-upgraded install is diagnosed instead of quietly certified healthy.

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.	A code-centered repository, where symbol and impact analysis can add value. On a mixed repository it is offered as optional rather than recommended, when there is enough code for structural analysis to be useful. Not proposed for document, research or writing projects.	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 is recommended: the repository is code-centered, so symbol and impact analysis can add value. OpenWiki is deferred until a clear audience and a stable need for generated navigation are established. Graphify is not proposed.
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
Graphify is recommended when the repository spans two or more artifact types that benefit from cross-file relationships. GitNexus is optional, offered when the mixed repository contains enough code for structural analysis to be useful. OpenWiki is deferred until collaborators demonstrate a need for maintained generated navigation.
General
Nothing is offered until inspection finds a concrete need — the same answer while the type is still uncertain.

Project Hub is not a fourth add-on. These three are derived views: rebuildable from material you already have, and never the thing being cited. A Hub is another authored tier — records an owner writes in one separate private repository and pushes down into yours, where they arrive read-only and stamped so the doctor can tell an untouched copy from an edited one.

What a Hub authors, and what a push may never send → Project Hub

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.