# Smriti — Version control for project reasoning state
Code has Git. Multi-agent reasoning does not. Smriti is version control for project reasoning state — versioned, structured, branchable snapshots so multiple coding agents coordinate on the same codebase without overwriting each other's thinking.

# 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.

See it coordinate View on GitHub →
Local-first · no API keys required Open source · MIT

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.

Code · Git
Reasoning · Smriti
commit
checkpoint Structured snapshot of reasoning state at an inflection point.
branch
fork Branch from any checkpoint to explore an alternative without losing the trunk.
diff
compare Structured diff of two checkpoints — decisions, tasks, claims.
revert
restore Return to a clean checkpoint when an experiment goes sideways.
working-tree drift
repo-state drift Flag when the live repo has moved past the checkpoint base.
no equivalent
active claims Advisory, time-bounded — agents see each other coming.
no equivalent
freshness checks "Has shared state moved since my base?" before checkpointing.
no equivalent
structured tasks & IDs Stable identifiers so two agents can talk about the same work.

The last threehave no Git equivalent. Git is built for one human committing serial code. Smriti is built for multiple agents writing reasoning state in parallel.

Why `HANDOFF.md` isn't enough

## Markdown 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 collision
# 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
What broke: two agents picked the same task. No claim, no freshness check, no shared task ID. Last write wins.
checkpoint · b0bc283 resolved
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=b0bc283 branch=main ahead=0
What's preserved: queryable fields, stable IDs, active claims, repo state. Two agents see each other.

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 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.

checkpoint · b0bc283 claude-code 30m ago
objective Ship the v2 website redesign.
decisions

- Stay zero-build (no framework, no node_modules).
- Use the braided-strand motif as the visual language.

in_progress

- implement landing page redesign id=website-v2

active_claims

- claude-code website-v2 · ttl 4h

repo_state head=b0bc283 · branch=main · ahead=0

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.

claude-code idle
working on

task pool · shared

- test deletion-safety-tests t-1
- implement deletion-safety-guard t-2
- doc update-quickstart t-3
- investigate failing-build t-4

codex idle
working on

Same task pool. No orchestrator. Watch each agent read the pool, claim something, and route around the other's claim.
0 / 5

Click any unclaimed packet to fire it manually click

This is the 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.

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.

repo timeline
smriti state my-project (excerpt)
## Repo state branch main · HEAD f4e5d6c · upstream +2/-0 - recorded checkpoint: abc1234 - repo is 2 commits ahead of checkpoint base - branch: matches - working tree: clean → reconcile before checkpointing

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:

~/Documents/GitHub/smriti smriti-dev
$smriti metrics smriti-dev
# smriti-dev — project metrics
## Coordination
129 checkpoints · 2 agents (claude-code: 79, codex-local: 50)
67 cross-agent continuations
87 claims · 97% completion · 48 with task IDs
## State quality
3.2 decisions/checkpoint · 1.8 tasks/checkpoint
66 with structured tasks · 64 with task IDs
7 milestones · 1 noise label
## Branches
0 active · 0 integrated · 0 abandoned

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 for the core coordination loop — setup, doctor, quickstart, state/current/metrics, claims, attach, and hand-written checkpoints all run on a local SQLite file. LLM-backed features — `checkpoint create --extract`, draft, review, the chat send loop — need a real provider (OpenAI / Anthropic / OpenRouter / local OpenAI-compatible). They refuse to run on the default mock adapter rather than silently committing placeholder content.

01

### Install

terminal 1

    git clone https://github.com/himanshudongre/smriti
    cd smriti
    make setup-local
    make dev-local         # backend, leave running

02

### Run

terminal 2

    cd smriti
    source backend/.venv/bin/activate

    smriti doctor          # verify install
    smriti quickstart      # seeded demo + 3-min walkthrough

After the walkthrough, `cd` into any of your own projects and run `smriti init my-project` to attach it. One Space per project.
requires Python 3.11+ · Node 20.19+ / 22.12+ Full setup guide →

## Build with the missing primitive.

Smriti is open source. It works today for solo builders running multi-agent workflows.

Star on GitHub Read the docs