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.
MonoMind AI Lab
Project Context
a durable project record for agents and people
Weeks away should never mean rebuilding the project from stale chats.
Small Markdown records, versioned beside the work, that outlive any one person, agent, or chat. A single repository needs nothing but what is on this page; Project Hub is there when you run several.
- NOW.md
- DECISIONS.md
- LEARNINGS.md
- plain Markdown, portable by design
install · one command
scroll →
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context init --target . --install-skills --apply
01
What Project Context actually is
Three core Markdown summaries live beside one project: current state, constraining decisions, and verified learnings. A full profile adds five operational kinds that agents write when their triggers fire — decisions, questions, tasks, designs, and incidents. An organisation running several projects can add a private Project Hub; one repository needs nothing else.
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.
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. The three core summaries answer what a returning session asks first; five writer-backed operational kinds preserve the detailed work that earned a durable record.
- work stops for the day
- the three core summaries and any triggered records are brought up to date
- the next session opens with the state in hand
Current Project State
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
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
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.
03
One command, or one prompt
Runs the CLI straight from the repo. No clone, no virtualenv. Swap --apply for --dry-run to print the plan first.
scroll →
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context init --target . --install-skills --apply
Keeps all ten subcommands on your path: init, update, record, capture, inspect, context, onboard, review, consolidate and doctor.
scroll →
pipx install git+https://github.com/monomind-ai-lab/project-context
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 19 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 nine 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.
Operational writer coverage
A full profile must carry the supported writer for decisions, questions, tasks, designs, and incidents. missing-record-writer catches folders that exist but no agent can safely fill.
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. The record works fully with none of them.
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.
What each one does, when it is offered, and how it relates to the record → Add-ons