Code has Git.
Multi-agent reasoning does not.
- Smriti is version control for project reasoning state — versioned, structured, branchable snapshots of what was decided, what's still open, and what each agent is doing right now. So multiple coding agents can coordinate on the same codebase without overwriting each other's thinking.
- -The problem
-Run Claude Code and Codex on the same project — or two Claude Code sessions — and they share no state. Each agent starts from scratch, re-discovers decisions already made, and occasionally duplicates work another agent is already doing.
-The standard workaround is HANDOFF.md / NOTES.md. That works until reasoning needs to branch, be compared, be restored, or be validated against the actual repo. Markdown is prose; it stops working the moment more than one agent needs to coordinate.
The Git analogy
-Git preserves code history: what changed, when, by whom, on which branch. Smriti preserves project reasoning: what was decided, what's still open, what each agent is doing right now, and how the recorded state compares to the live repo.
-| Code (Git) | Reasoning state (Smriti) |
|---|---|
| commit | checkpoint — structured snapshot of reasoning state |
| branch | fork from any checkpoint to explore an alternative |
| diff | smriti compare — structured diff of two checkpoints |
| revert / checkout | smriti restore — return to a clean checkpoint |
| working-tree drift | repo-state drift — flags when the repo has moved past the checkpoint |
| — | active claims — advisory coordination so agents see each other coming |
| — | freshness checks — "has state moved since my base?" before checkpointing |
| — | structured tasks + IDs — collision detection at the task level |
The first five rows extend the Git analogy. The last three are coordination primitives Git doesn't have — because Git is built for one human committing serial code, and Smriti is built for multiple agents writing reasoning state in parallel.
-How it works
--
-
-
-
1. Attach the repo
-
-smriti init my-projectcreates a Space, installs the Claude Code and Codex skill packs into the project directory, writes the SessionStart hook, and drops a.smriti.jsonat the repo root. Per-project — attach once, multiple repos isolate cleanly.
- -
-
2. Agents read state first
-At session start, the agent reads the current state brief — objective, decisions, assumptions, tasks, open questions, artifacts — plus the
-## Repo statesection comparing the working repo to the HEAD and branch the last checkpoint recorded.
- -
-
3. Declare claims before working
-The agent calls
-smriti claimwith a scope before starting work. Claims are advisory, time-bounded, and visible in every other agent's state brief. Two agents see each other coming.
- -
-
4. Checkpoint at inflection points
-At a real decision or handoff the agent writes a structured checkpoint. The next session — same agent or a different one — reads it as if it had been there for the work.
-
-
Inside an attached repo, the everyday commands resolve the Space automatically — no <space> argument needed:
smriti state # continuation brief — read first each session
-smriti current # compact snapshot: direction, attention, open work
-smriti metrics # project coordination KPIs
- What Smriti is not
-Not markdown
-HANDOFF.md / NOTES.md work until you need claims, freshness, branching, drift detection, or coordination at all.
Code has Git.Multi-agent reasoning does not.
+Smriti is version control for project reasoning state. Versioned, structured, branchable snapshots of what was decided, what's still open, and what each agent is doing right now — so multiple coding agents coordinate on the same codebase without overwriting each other's thinking.
+ -Not memory
-Smriti stores structured snapshots at inflection points, not a running log of everything an agent said or saw. State is queryable, not narrative.
-Not an orchestrator
-Smriti describes state. It does not assign tasks, schedule work, or route agents. Agents make their own decisions from shared metadata.
+What markdown can't reliably provide
--
-
- Active claims — who is working on what right now, with a TTL -
- Freshness checks — has the state moved since my base before I checkpoint? -
- Task IDs tied to claims — collision detection at the task level -
- Repo-state drift detection — recorded state vs the live repo, with N-commits-ahead / branch-mismatch surfacing -
- Branchable, comparable, restorable reasoning —
smriti fork,smriti compare,smriti restore
- - A current-state surface — one well-defined brief multiple agents read at session start -
Built with Smriti
-The coordination substrate was built with Claude Code and Codex working in parallel on the same codebase, coordinating through Smriti's own state. smriti metrics smriti-dev:
The strongest proof: two agents started near-simultaneously, read the same task surface (four tasks with stable IDs and intent hints), and independently picked different complementary tasks — one chose [test], the other chose [implement] — without any human routing. No orchestrator. No task queue. Just structured metadata on shared state.
What it looks like
-
-
- smriti state --compact) and the project health KPIs (smriti metrics).
- The missing primitive
+Git tracks code history.
Nothing tracks reasoning history.
+ A single human committing serial code has Git. Multiple agents writing reasoning state in parallel have nothing. Smriti closes the gap with the same primitives, plus three Git was never built to have.
+ +Try it in 5 minutes
-The core coordination loop runs entirely on a local SQLite file. No Docker, no API keys, no cloud required. API keys come in only for optional LLM-assisted features (extract, draft, review).
-You'll need Python 3.11+ and Node 20.19+ / 22.12+.
--
-
-
-
1. Install
+Why
+HANDOFF.mdisn't enoughMarkdown is prose.
+
Coordination is structure.A shared markdown file works until two agents need to edit it at once, ask "is my base still current?", or compare two takes on the same decision. The moment coordination needs to be queried, branched, or validated against the repo, prose stops working.
+ ++ ++++ ++ + + HANDOFF.md + + prose +++ # Current work + - Status: refactoring rate-limit middleware + - Owner: ? + - Base: main, but unsure if still current + + ## In progress + - [claude-code] writing the guard logic + - [codex] writing the guard logic too + - [codex] (no idea claude was on this) + + ## Open + - need tests + - need someone to update the README ++ +++ ++ + + checkpoint + + structured +++ objective: close deletion-safety thread + decisions: + - require force=true for non-empty deletes + - 409 if claim is unresolved + in_progress: + - [implement] deletion-safety-guard id=t-2 + - [test] deletion-safety-tests id=t-1 + active_claims: + - claude-code → t-2, ttl 4h + - codex → t-1, ttl 4h + repo_state: + head=5d00ba9 branch=main ahead=0 ++ +
What Smriti is
+A coordination substrate, not a notebook.
+ +Smriti is a small backend, a CLI, an MCP server, and skill packs for Claude Code and Codex. It records structured snapshots at inflection points — not a running log of everything an agent saw — and exposes them as a queryable state brief every agent reads at session start.
+One Space per project. Per-project attachment via .smriti.json. Local SQLite by default; Postgres for shared/team workflows. No orchestrator. No router. No assignment logic. Agents read the same structured state and decide for themselves.
The hard part isn't storing reasoning — it's making it self-validating against the live repo and safe for parallel writers. That's the work.
+-
+
- Use GitHub Actions source, not legacy branch-folder. +
- Keep
.nojekyllas a forward-compatible marker.
+
-
+
- + implement + publish via Pages + id=website-deploy-target + +
Multi-agent coordination — protocol, not orchestration
+Two agents. Same task pool.
Complementary work — no orchestrator.
+ Each agent reads the shared state, sees the others' active claims, and picks something complementary. The "routing logic" is structured metadata, not a queue manager.
+ +This is the actual pattern that built this site. Same task pool, two agents, complementary picks, no human routing. smriti metrics smriti-dev below shows the cumulative coordination cost — 87 claims, 97% completion, 67 cross-agent continuations.
Drift & trust
+Reasoning state stays honest about the repo.
+A reasoning snapshot is only useful if it tracks the code it's reasoning about. Every checkpoint records the repo HEAD and branch. Every state brief compares it back to the live repo — and surfaces the drift before another agent acts on stale ground.
+ +The drift signal isn't an alert popup — it's part of the state brief every agent reads at session start. If you and the recorded state disagree, you see it before you act on it.
+Built with Smriti
+The substrate was built on itself.
+Claude Code and Codex co-built this project end-to-end through Smriti's own state. Real numbers from the project Space, as of today:
+ +The 67 cross-agent continuations are the headline. Each is a moment where one agent ended a session, the other started, read the shared state, and continued the same thread as if it had been there for the work.
+Try it
+Up and running in minutes.
+No Docker, no API keys, no cloud required. The core coordination loop runs on a local SQLite file. API keys come in only for optional LLM-assisted features.
+ +Install
+ terminal 1 +git clone https://github.com/himanshudongre/smriti
cd smriti
-make setup-local # backend venv + CLI + frontend, no Docker
- Start the backend in one terminal and keep it running:
-make dev-local # backend on http://localhost:8000
- In a second terminal, activate the CLI before running smriti commands:
Run
+ terminal 2 +cd smriti
-source backend/.venv/bin/activate
-
- 2. Confirm — smriti doctor
-smriti doctor
- Backend reachable, CLI/backend versions aligned, providers configured. If anything's off, doctor tells you what.
-3. See it work — smriti quickstart
-smriti quickstart
- Seeds a demo Space (a rate-limit feature built by two agents, with a branch explored and dropped) and prints a guided ~3-minute walkthrough. Works without API keys.
-4. Attach your own project
-cd /path/to/your-project
-smriti init my-project
- Writes the skill packs, the SessionStart hook, and .smriti.json into the project directory, binding the repo to the new Space.
5. Daily workflow — no <space> needed
-smriti state # continuation brief
-smriti current # compact snapshot
-smriti metrics # coordination KPIs
- After the walkthrough, cd into any of your own projects and run smriti init my-project to attach it. One Space per project.
Try it. Star it. Build with it.
+ +Build with the missing primitive.
Smriti is open source. It works today for solo builders running multi-agent workflows.