Smriti — Version control for reasoning.

Conversations become structured state, not disposable logs.

Smriti is a versioned AI workspace. It turns conversations into structured, immutable snapshots called Checkpoints that you can carry across models, fork into new reasoning paths, and compare later.

Smriti owns the reasoning state. Models are interchangeable.

For example: you spend an hour with GPT-4o working through an architecture decision, checkpoint the conclusion, then continue the same thread in a new session using a different model. No re-explanation, no lost context.

---

Demo preview

Click to watch a 3–4 minute walkthrough of branching, checkpoints, and comparison:

---

The problem

You spend an hour working through a hard problem. You reach a clear decision. Then you need to step away, switch models, or revisit an earlier direction.

There is no clean way to do this. The only record is a flat transcript. You cannot return to the exact state you were in an hour ago. You cannot fork the conversation to explore a different direction without contaminating the original thread. You cannot switch models without re-explaining everything from scratch.

Smriti fixes this by treating reasoning state as a first-class artifact, versioned and isolated from the event stream that produced it.

---

What you can do with it

• Return to any prior state. Mount any Checkpoint; the model receives exactly that state as context, nothing more. Later work does not leak backward.
• Switch models mid-session. Checkpoints carry state across providers. Switch from OpenAI to Anthropic without re-explaining the problem.
• Fork a line of reasoning. Branch from any Checkpoint into a new session. Both threads remain live in the same Space.
• Compare branches. Diff any two Checkpoints across branches to see exactly where decisions diverged.

---

Beyond chat: reasoning state for agents

Smriti is not limited to chat workflows.

Agents also struggle with state. Multi-step reasoning chains become hard to debug, reproduce, or branch. Once an agent run diverges, there is no clean way to return to a prior state or explore alternatives in parallel.

Smriti provides a structured state layer that agents can use:

• Persist intermediate reasoning as checkpoints
• Resume from any prior state deterministically
• Fork execution paths to explore alternatives
• Compare outcomes across runs

This makes agent behavior inspectable, reproducible, and debuggable.

---

Quick start

Prerequisites

• Python 3.11+
• Node 18+
• PostgreSQL 14+
• At least one LLM provider API key (OpenAI, Anthropic, or OpenRouter), or use Mock Mode to run without any keys

git clone https://github.com/himanshudongre/smriti
cd smriti

# Copy environment template
cp .env.example .env

# Install all dependencies and run database migrations
make setup

# Start backend (terminal 1)
make dev

# Start frontend (terminal 2)
make dev-frontend

Frontend: http://localhost:5173 | Backend API: http://localhost:8000

No API key? Enable Mock Mode in the compose bar to run with scripted responses and no provider calls.

Docker

make up       # Start all services (postgres + backend + frontend)
make logs     # Follow logs
make down     # Stop all services

---

Try the demo

demos/branching-reasoning-demo/ contains a complete, repeatable walkthrough demonstrating Smriti's branching and comparison workflow. Includes step-by-step instructions, exact messages to paste, expected diff output, and a presenter talk track.

demos/branching-reasoning-demo/README.md

---

Core Concepts

Space

A Space is the long-lived container for a line of work. It holds the full history of Checkpoints created within that work and all Sessions associated with it.

Analogy: a Git repository, but for a thinking process rather than a codebase.

Spaces are named and persistent. You might have one for a product architecture decision, another for a research topic, another for a client engagement.

Session

A Session is a live chat runtime. It may be attached to a Space (and thus have access to that Space's Checkpoint history) or standalone (no persistent state).

A Session has an active provider and model. Switching provider or model within a Session does not lose conversational history — Smriti stores Turns independently of any provider session.

Checkpoint

A Checkpoint is a structured, immutable state snapshot. It contains:

Field	Description
Title	3–5 word label for the state
Objective	The goal being worked toward at this point
Summary	Narrative of what was figured out
Decisions	Explicit choices made — only what was stated, not inferred
Tasks	Concrete action items identified
Open Questions	Unresolved questions at this point
Entities	Key concepts, tools, systems, or proper nouns

Checkpoints are created manually at meaningful points — before switching models, before stepping away, when a significant decision is reached. The Draft with AI feature uses a background intelligence model to extract a draft from the current session's active Turns; the user reviews and saves.

A Checkpoint is never created automatically. This is intentional: automatic checkpointing produces noise, not signal.

Turn

A Turn is a single unit in the event stream: one user message or one assistant reply, with its provider, model, and sequence number recorded. Turns are append-only and never edited.

Turns are the raw material. Checkpoints are the distillate.

---

The Context Modes

Mode	What the model sees
FRESH	No Checkpoint context. Blank slate. Only the current Turn.
HEAD	The latest Checkpoint in the attached Space, plus recent Turns in this Session.
MOUNTED	A specific Checkpoint, plus only Turns created after mounting. Nothing else.
FORKED	The fork-source Checkpoint as base context, plus Turns created in this fork session.

The MOUNTED mode is the key differentiator.

When you mount a specific Checkpoint, Smriti records the sequence number of the last Turn at the moment of mounting. All subsequent requests pass only Turns with sequence numbers above that boundary. Turns from other sessions, from other providers, or from work that happened after that Checkpoint was created — none of it enters the context. The isolation is enforced at the data layer, not by prompt instruction.

---

How It Works

Starting a session

Open the workspace. A new Session is created automatically. By default it has no Space attached (FRESH mode).

Attaching a Space

Click the Space button in the thread header. Select an existing Space or create one. Choose a memory scope:

• Latest checkpoint only — the most recent Checkpoint provides base context
• Latest 3 checkpoints — the three most recent Checkpoints provide layered context

Creating a Checkpoint

When you reach a meaningful point — a decision, a model switch, the end of a work block — click the Checkpoint button in the thread header.

The Checkpoint form opens with empty fields. Click Draft with AI to have the background intelligence model extract a draft from the current session's active Turns. The draft reflects only the active context mode (FRESH, HEAD, or MOUNTED). Review, edit, and save.

Mounting a Checkpoint

Open the Checkpoint history panel by clicking the context badge in the thread header. Find the Checkpoint you want to return to. Click Mount.

The header updates to show MOUNTED · <hash>. Any Turn you send from this point is resolved against that Checkpoint's state only.

To return to HEAD mode, click Unmount in the history panel.

Forking a Session

Open the Branch Tree for a Space. Click Fork on any Checkpoint. Give the branch a name. A new Session is created, seeded from that Checkpoint's state, with a clean Turn history.

The fork session starts in FORKED mode. Its reasoning develops independently from the main branch. Both branches remain live in the same Space.

Comparing Checkpoints

In the Branch Tree, select any two Checkpoints across any branches and click Compare. The diff view shows decisions, tasks, and summaries side by side with per-branch and shared items clearly marked.

Switching providers

Change the provider and model in the session toolbar. The Session continues uninterrupted. Smriti passes the same Checkpoint context and Turn history to the new provider. No re-explanation required.

---

Current Limitations

• Single-user; no authentication
• No merging of divergent Checkpoint lines
• No streaming responses — each Turn is a synchronous request/response cycle
• Transcript ingestion via paste (V1 API) is a legacy feature; not the primary workflow
• No mobile UI
• No MCP or browser extension integrations

---

Provider Configuration

Smriti uses two independent provider slots:

Chat provider — the model you converse with. Selected per-session in the UI toolbar. Supports: OpenAI, Anthropic, OpenRouter.

Background intelligence — a separate model used for Draft with AI and session auto-titling. Configured server-side. Not visible in the chat UI.

YAML configuration (recommended)

Copy backend/config/providers.example.yaml to backend/config/providers.yaml and fill in your keys:

providers:
  openai:
    api_key: "sk-..."
    default_model: "gpt-4o"

  anthropic:
    api_key: "sk-ant-..."
    default_model: "claude-sonnet-4-6"

  openrouter:
    api_key: "sk-or-..."
    base_url: "https://openrouter.ai/api/v1"

chat:
  default_provider: "openrouter"

background_intelligence:
  provider: "openai"
  model: "gpt-4o-mini"

Environment variables

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
SMRITI_DEFAULT_PROVIDER=openrouter
DATABASE_URL=postgresql://smriti:smriti@localhost:5432/smriti

Environment variables take precedence over YAML values. API keys are never returned by any API endpoint.

Mock Mode

The UI includes a Mock Mode toggle (compose bar) that uses a deterministic mock adapter — no API calls, scripted responses. Useful for testing checkpoint and session mechanics without a live provider key.

---

Technical Stack

Layer	Technology
Backend	FastAPI, SQLAlchemy, Alembic, Python 3.11+
Database	PostgreSQL
Frontend	React 18, TypeScript, Vite, Tailwind CSS
Provider adapters	OpenAI SDK, Anthropic SDK, OpenRouter (OpenAI-compatible)

The backend API is versioned by product generation. V4 handles chat sessions and message sending. V5 handles checkpoint and lineage operations. V1 and V2 are legacy endpoints retained for compatibility but not part of the current primary workflow.

---

Roadmap

• Streaming responses
• Multi-user Spaces with authentication
• Provider expansion (additional providers and local models)
• Source Turn range recorded on Checkpoints (which conversation produced this snapshot)
• MCP integrations
• Checkpoint merging

---

Further Reading

• ARCHITECTURE.md — system model, checkpoint isolation mechanism, provider abstraction, API versioning
• docs/API.md — endpoint reference for V4 (chat) and V5 (checkpoint and lineage)
• DECISIONS.md — key architectural and product decisions
• CONTRIBUTING.md — how to set up the dev environment and contribute