Smriti was repo-local wiring: every command needed an explicit <space>, and
the SessionStart hook hard-coded the space name, so working across projects
and sessions meant re-stating the space constantly.
Add a `.smriti.json` attachment file at the repo root binding the repo to a
space. The CLI resolves `<space>` from it — walking up from the working
directory the way git finds `.git` — so `<space>` is now optional on the
everyday commands (state, current, metrics, claim, checkpoint, branch,
worktree). `smriti attach <space>` is the explicit binding verb (`smriti
attach` with no argument shows the current binding); `smriti init` also
writes the attachment. The generated SessionStart hook is now space-agnostic
— `smriti state --compact` resolves from the attachment, so the hook is
identical for every project and survives re-attaching.
`space delete` still requires an explicit space. No backend changes —
attach/init reuse the existing set_project_root endpoint.
A fresh install opens to an empty space, so Smriti's value — which only
shows once reasoning has accumulated — is invisible on day one. `smriti
quickstart` seeds one small, finished project (a rate-limiting feature
built by two agents, with a branch explored and dropped) and prints a
short guided walkthrough.
The demo space `smriti-demo` carries a marker in its description: --remove
only deletes a marked space, --reset rebuilds it, and seeding rolls back a
half-built space on failure. The fixture is plain structured data with
content-integrity tests guarding counts, intent types, note kinds, the
demo marker, and branch divergence.
Packaging/readiness pass — documentation only, no feature or behavior change.
- REPO_STRUCTURE.md, CONTRIBUTING.md: corrected test counts (156 integration,
133 unit, 151 CLI), local-first setup flow (make setup-local / dev-local),
command count, new routes/types/test files.
- README.md: refreshed dogfood metrics, added Project Current State and
smriti doctor to the surfaces, SQLite to the tech stack.
- cli/README.md: MCP tool count 17 -> 21 (added the four worktree tools),
documented the smriti worktree commands.
- ARCHITECTURE.md: API table now lists the Project Current State and metrics
endpoints; new Database modes section (local SQLite / Postgres).
- DECISIONS.md: recorded the local-first SQLite mode and Project Current
State surface decisions.
- AGENTS.md: regenerated from skill pack template v2.3 (was a stale v1.5
render); the .claude/ claude-code render was likewise refreshed locally.
.env.example, docs/DEMO_SCRIPT.md, and CLAUDE.md were reviewed and left as-is.
cli/README.md:
- Add an "Installing the Smriti skill pack" subsection between the MCP
server section and the Commands reference. Walks through the target
list (claude-code, codex), the CLI install flow, the MCP-tool flow
(read the returned markdown, write via host file tools), and the
verification criterion ("agent calls state unprompted, never writes
HANDOFF.md").
- Update the MCP tools table to 13 entries (add smriti_install_skill).
- Update the Commands reference to include smriti skills list/show/
install and the new --main-only flag on smriti state.
- Update the "Using Smriti from a coding agent" walkthrough to note
multi-branch state as the default, with caps and the --main-only
escape hatch.
README.md (root):
- Expand the agent-facing surfaces section to list four surfaces, not
three: chat UI, CLI, MCP server, agent skill pack. Explain what the
skill pack does in one paragraph.
- Update the "Where this is going" outlook to acknowledge that the
transport gap is closed, the fluency gap is what the skill pack
addresses, and the open questions are now shape questions.
DECISIONS.md:
- Add "Why skill packs are a first-class surface, not documentation" —
records the reasoning for shipping versioned instruction files into
agent host project directories rather than a docs site, and explains
why Section 5 ("When NOT to checkpoint") gets equal weight to "When
to checkpoint."
- Add "Why smriti state is multi-branch by default" — records why the
default was flipped, what the hard caps are, that divergence
detection reuses the compare normalization, and that --main-only /
main_only=True preserves the legacy path for scripts.
ARCHITECTURE.md:
- Split the agent-facing backend section into runtime surfaces (CLI,
MCP, chat UI) and the onboarding surface (skill pack) to make the
distinction between how agents call Smriti and how they learn to
call Smriti explicit.
- Expand the CLI + MCP surface descriptions to reference the new V4
state endpoint and the new smriti_install_skill MCP tool (13 tools
now).
- Add a "Multi-branch state" subsection documenting the new endpoint,
the hard caps, the reuse of _diff_lists from lineage, and the
backward-compat story via --main-only / main_only=True.
- Update the API versioning table to note /api/v4/chat/spaces/{id}/state
as the agent-facing default alongside /head.
Five rounds of dogfood testing closed the basic agent handoff loop and MCP
shipped as the second transport. Update the docs to match:
- cli/README.md: replace the brief "Typical agent workflow" + "Multi-branch
workflow" sections with a transport-agnostic "Using Smriti from a coding
agent" walkthrough. CLI commands and their MCP tool equivalents are shown
side by side. Covers orient → work → checkpoint → hand off, the extractor
path (no hand-written JSON anymore), and the branching/compare/restore
flow.
- README.md (root): list MCP as a third surface alongside the chat UI and
CLI. Update the "Where this is going" outlook to acknowledge that the
handoff loop is proven and the open questions are now shape questions,
not transport questions.
- ARCHITECTURE.md: add MCP server as a third entry in the agent-facing
backend section, with the deliberate differences from the CLI (no cwd
auto-capture, no per-tool confirmation) spelled out.
- DECISIONS.md: keep the original "why CLI first, not MCP" entry as
historical context and add a "Shipping MCP as the second transport"
entry recording the design decisions made at ship time (same package,
FastMCP, stdio only, 12 tools, extract-only create_checkpoint, empty
project_root default, MagicMock unit tests).
Round 5 dogfood surfaced three small friction items:
- smriti_list_checkpoints only rendered short hashes, forcing agents to
make a second round trip to get the UUID they needed for fork/compare/
restore. format_commit_list now appends the full UUID in parentheses
when c["id"] is populated; legacy callers without ids still render a
clean line. CLI output benefits equally since formatters are shared.
- The mcp SDK logs "Processing request of type ..." at INFO on every
tool call, cluttering host log panels. smriti-mcp main() now defaults
the mcp logger to WARNING. Set SMRITI_MCP_LOG_LEVEL=INFO (or DEBUG)
in the host's env block to re-enable verbose logging when debugging.
- Add README notes acknowledging that the mcp SDK negotiates the
protocol version on its own during initialize, and documenting the
new log-level env var.
Round 4 validated that the Smriti CLI surface is complete. This is the
next transport: an MCP stdio server that exposes the same operations as
tools inside MCP-aware hosts (Claude Code, Cursor, Windsurf) so agents
can read and write reasoning state natively in their session instead of
shelling out to the `smriti` binary.
The server lives inside the existing CLI package as a sibling to
client.py and main.py. One `pip install -e ./cli` installs both the
`smriti` and `smriti-mcp` console scripts. Architecture is a thin shim:
each tool builds a SmritiClient, calls 1-2 client methods, pipes the
result through an existing formatter, and returns a string. FastMCP
auto-wraps the string into TextContent. Errors raise SmritiToolError
(wrapping SmritiError with HTTP status + structured detail); FastMCP
converts raised exceptions into MCP error responses.
Zero reimplementation of API logic, zero duplicated formatting, zero
changes to client.py, formatters.py, main.py, or the backend.
Twelve tools, 1:1 with the CLI verbs:
smriti_list_spaces smriti_state
smriti_create_space smriti_list_checkpoints
smriti_delete_space smriti_show_checkpoint
smriti_create_checkpoint smriti_review_checkpoint
smriti_delete_checkpoint smriti_restore
smriti_fork smriti_compare
Two deliberate differences from the CLI:
- No `-y` confirmation flag on destructive tools. The MCP host's
tool-approval UI is the gate.
- smriti_create_checkpoint uses the extract path only (no
--from-json mode) and does NOT auto-capture cwd as project_root.
MCP servers run in the host's arbitrary working directory, so
cwd would plant garbage paths. Callers pass project_root
explicitly when they want it populated.
Testing: 33 unit tests across all 12 tools using a
MagicMock(spec=SmritiClient) fixture in tests/conftest.py. Each tool
has at least one happy path and one error path; the complex ones
(smriti_state, smriti_create_checkpoint, smriti_delete_checkpoint)
have extra tests for their branches (no-checkpoints short-circuit,
dry-run, existing-session, 409-with-dependents formatting,
409-with-non-dict-fallback, empty-content pre-check).
End-to-end stdio protocol smoke verified independently: the
`smriti-mcp` binary responds to `initialize` with protocol version
2025-03-26 and returns all 12 tools on `tools/list`. Ready for
`mcp dev smriti_cli.mcp_server:mcp` Inspector UI exploration or
direct Claude Code connection.
cli/README.md gets a new MCP server section with installation,
example Claude Code config, tool list, and notes on the project_root
and confirmation-gate differences from the CLI.
Round 3 of the dogfood confirmed that every multi-branch CLI command
works end-to-end, but the single biggest remaining friction is still
checkpoint payload construction. Each agent hands off a ~15-18 KB
markdown document; turning that into the Smriti schema (decisions,
assumptions, tasks, open_questions, entities, artifacts) is three
minutes of hand-written JSON per checkpoint and adds no product value.
This build adds an LLM-powered extractor that collapses that work into
one pipe command:
cat /tmp/r3_agent_a_output.md | smriti checkpoint create my-project \
--extract --author-agent codex-A
The CLI reads stdin as freeform markdown, calls the new
POST /api/v5/checkpoint/extract endpoint, maps the returned fields
into a commit payload, and writes the checkpoint. --dry-run prints the
extracted payload without committing so users can review first.
--extract and --from-json are mutually exclusive.
Backend architecture mirrors the existing review endpoint: stateless
LLM call (no session or commit ID required), uses the same background
intelligence provider (cfg.background.provider / cfg.background.model)
as draft and review, same JSON-mode prompt shape, same 502-on-parse-
error pattern. The extractor endpoint differs in one small way: it
passes allow_mock=True to get_adapter so unconfigured test envs fall
back to MockAdapter without raising 500. Production envs always have
a real provider configured and never hit this fallback.
The extractor is the first LLM-backed endpoint that gets tested
against a real mock response. To make that work, MockAdapter.send now
detects response_format={"type": "json_object"} in kwargs and returns
a canned JSON blob covering every field any current Smriti endpoint
looks for (title, objective, summary, decisions, assumptions, tasks,
open_questions, entities, artifacts, issues, suggestions). Existing
chat.send text-mode tests are unaffected because they don't pass
response_format. This also unblocks future tests for draft and review.
Manual verification against a real OpenAI provider: piped a realistic
23-line handoff markdown with 4 decisions, 3 assumptions, 3 tasks,
2 open questions, and a python code block. The extractor returned
exactly those items in the right fields (4/3/3/2/1) and produced a
valid checkpoint with all fields populated. Round 4's load-bearing
claim — zero hand-written JSON per checkpoint — is now achievable.
153/153 backend tests pass (149 pre-existing + 4 new extract tests).
Cross-agent handoffs need to know two things the old schema did not
carry: where the project lives on disk (so the receiving agent opens
the right repo), and which agent wrote the checkpoint (so branches
can be attributed when two agents have forked the same tree). Round 1
of the dogfood lost the first one — Agent A designed files at one
path and Agent B wrote them at a different path because nothing in
the schema carried "where we are". Round 2 worked around it by putting
the path in the prompt, but the schema still had no slot for it.
This build adds a `project_root` column to the commits table (nullable
TEXT, no backfill), plumbs it through the V2 commit-create path and
V4 chat-commit path, and has `smriti checkpoint create` auto-capture
the current working directory by default. `--project-root /path`
overrides and `--no-project-root` opts out.
`author_agent` already existed on the model but the V4 chat-commit
endpoint hardcoded it to the session's active provider (e.g.
"anthropic"), so it was a provider name, not an agent identifier.
This build makes the request's `author_agent` field win when provided
and falls back to the session provider only when it isn't. CLI adds
`--author-agent <name>` so agents can tag themselves cleanly as
"claude-code" or "codex-local" rather than the underlying provider.
Both fields surface in `smriti state`, `smriti checkpoint show`, and
`smriti restore` meta lines — `by <agent>` and `at <path>` (with $HOME
tilde-expanded for readability). The meta line elides each segment
cleanly when the field is null, so old checkpoints without either
value still render correctly.
While I was here, flipped `smriti state` to show full artifacts by
default. `--preview` is the new way to get truncated previews.
`--full-artifacts` is kept as a no-op alias so existing scripts that
explicitly passed it still work. The CLI is agent-first and agents
want the full content for handoff; humans wanting a quick glance can
pass `--preview`.
149/149 backend tests pass (147 pre-existing + 2 new: round-trip of
the two fields and the author_agent fallback regression).
Round 2 of the agent handoff dogfood showed that every multi-branch
operation required reaching past the CLI into curl: fork had no CLI
command, `smriti checkpoint create` always spawned a fresh session with
no way to attach to a forked one, and the compare endpoint returned
useless output (common_ancestor_commit_id was missing from the response,
and shared-set matching was exact-string so two agents phrasing the
same commitment differently showed zero overlap).
This ships the full CLI surface for multi-branch workflows plus the
backend fixes that make compare actually useful:
smriti fork <checkpoint-id> [--branch <name>]
smriti restore <checkpoint-id>
smriti compare <checkpoint-a> <checkpoint-b>
smriti checkpoint create <space> --session <session-id>
The compare endpoint now walks parent chains to compute a lowest
common ancestor (bounded to 1000 steps with a cycle guard) and returns
it on CheckpointDiff as an optional uuid. Shared-set matching uses a
lightweight lowercase + punctuation-strip + whitespace-collapse
normalization for keying, but returns the original A-side strings so
the output stays readable. Four new compare tests cover direct and
two-step LCA, null LCA for unrelated checkpoints, and normalized
shared-set matching. Existing compare tests still pass unchanged
because their data ("Use Redis" vs "Use Postgres") is distinct at any
sensible normalization level.
`smriti restore <checkpoint>` is a pure read — it renders any
checkpoint as a continuation brief matching `smriti state <space>`
shape. `smriti fork` derives the space from the checkpoint so the
user does not have to pass it separately. `--session` on checkpoint
create is purely additive: when absent, the existing auto-session
behavior is unchanged.
147/147 backend tests pass (143 pre-existing + 4 new).
Introduce a thin Python CLI that wraps the backend REST API. Seven
commands: space list, space create, state, checkpoint create,
checkpoint show, checkpoint list, checkpoint review. Reads piped
JSON on stdin for checkpoint create, prints a continuation-oriented
markdown brief for state. Supports --json on every command for
structured output.
Fixes a V2 schema drift where the commit response omitted
assumptions and artifacts, so the CLI can read full checkpoints
via the cleaner V2 single-resource endpoints. Updates README,
ARCHITECTURE, and DECISIONS to frame Smriti as a reasoning-state
backend with the chat UI and CLI as two clients of the same core.
