In review • A changed diagram or chart renders before and after side by side, with the source diff underneath. • Math, callouts and embeds render inside the rendered diff.

Performance and safety • KaTeX and Shiki render on the server. Mermaid and Vega-Lite render in the browser, lazy-loaded only on pages that use them, with the rendered SVG cached by content hash. • Mermaid runs with its strict security level. Chart specs are validated against the Vega-Lite schema and a data-source allowlist. • Embeds resolve at most three levels deep and never loop.

Portability On GitHub, tables, task lists, footnotes, callouts, math and Mermaid render natively. chart blocks and embeds show as plain source, which stays readable. Export can optionally add a static SVG snapshot under each chart for tools that can't render them.

Proposals and review A proposal is a suggested create or update against a specific base revision. Review is the product's signature experience, so it gets the most design care.

Proposal lifecycle stateDiagram-v2 [] --> open: propose_change (valid) open --> changes_requested: reviewer requests changes changes_requested --> open: update_proposal open --> merged: reviewer merges open --> rejected: reviewer rejects open --> withdrawn: author withdraws changes_requested --> rejected merged --> [] rejected --> [] withdrawn --> [] Invalid submissions never create a proposal; the caller gets errors instead. Proposals left open for 30 days are marked stale but stay open.

What a proposal contains

Review screen • Header: summary, author with agent glyph, action, target path, age, validation badge. • Rendered diff (default): the document rendered as it will look, with word-level insertions highlighted green and deletions struck red. Unchanged sections collapse to one line, expandable. • Source diff (D to toggle): line-level Markdown diff for precise checking. • Frontmatter diff: a table of changed fields: field, before, after. Metric changes show the delta. • New documents: shown fully rendered with a "new" tag, not as a diff. • Rationale: shown under the header when present. • Actions: Merge (M), Request changes (C, requires a note), Reject (R, optional reason), Next (J), Previous (K), Edit before merge (E). Edit before merge lets the reviewer fix a typo in the proposal and merge in one step. The revision records both the agent and the reviewer.

Diff engine Parse both versions into Markdown blocks with remark, align blocks by position and similarity, then run a word-level diff within changed blocks. This gives prose-readable diffs instead of GitHub-style line diffs.

Merge and conflicts

1. If base_revision_id equals the current head, merge directly.
2. If not, run a three-way merge of base, head and proposal.
3. A clean merge shows a notice "Rebased onto latest" and merges normally.
4. A conflict marks the proposal conflicted. The reviewer resolves side by side, or requests changes so the agent re-reads and resubmits.

On merge In one database transaction: create the revision, move the document head, recompute links and backlinks, write metric points for experiments, and log an audit event. The agent sees merged through get_proposal.

MCP server and API Ledger hosts a remote MCP server at /api/mcp using the official MCP TypeScript SDK with Streamable HTTP transport. Agents connect with a URL and either an API key or an OAuth sign-in; no CLI, no GitHub. A REST API mirrors the same operations for scripts.

Connecting an agent { "mcpServers": { "ledger": { "url": "https://ledger.example.com/api/mcp", "headers": { "Authorization": "Bearer lk_memento_…" } } } } Settings → Agent keys shows this snippet pre-filled, with copy buttons for Cursor, Claude Code and a generic client.

Connecting assistants One endpoint serves every client. Developer tools use API keys in headers; consumer assistants use OAuth, where the user pastes the URL, signs in to Ledger and approves scopes. Both paths reach the same ten tools.

Settings → Connect shows one card per client with its exact setup steps and a copy button. Client setup flows change often, so each card links to that client's current docs.

OAuth for MCP • Implements the MCP authorization spec: OAuth 2.1 with PKCE, protected resource metadata at /.well-known/oauth-protected-resource, authorization server metadata, and dynamic client registration. • Two scopes only, each with a plain-language purpose string for approval screens: read ("Read documents, templates and metrics in this space") and propose ("Suggest new or changed documents for your review; cannot publish anything"). • The consent screen lets the user pick the space and scopes. A grant is always tied to one space. • Access tokens last 1 hour; refresh tokens last 30 days, rotate on use and are revoked with the grant. • There is no merge scope, so no assistant can ever be granted publishing power, even by mistake.

Capture from anywhere Phone assistants turn Ledger into a capture surface. A spoken note becomes a proposal: "Log to Memento that v7 summaries felt repetitive on long entries." The assistant files it as an experiment with status planned or as a doc note, and it waits in the Inbox. Validation still applies, so a vague note gets a structured error the assistant can resolve by asking one follow-up question.

Tools Ten tools. All of them read, validate or propose; none merge, delete or administer.

The space comes from the key, so tools never take a space argument.

Error format Every error is structured so agents can self-correct without a human: { "valid": false, "errors": [ { "field": "harness", "code": "link_unpinned", "message": "harness link needs a version", "hint": "Use memento-journal@7. Active version is 7." } ] }

Tool descriptions matter Each tool's description tells agents the workflow: call get_context first, get_template before creating, validate when unsure, one document per proposal, never invent metric values. agents.md repeats these rules in the space owner's own words. get_context and get_template also return a short syntax reference for callouts, Mermaid, math, embeds and charts, including a metrics-backed chart example. Agents then produce diagrams and charts that render on the first try.

REST API Same auth header, JSON in and out, under /api/v1.

This lets Memento's own eval scripts post experiment results directly after a run, with no agent in the loop.

Limits • 60 requests per minute and 30 proposals per hour per key; 429 with retry-after beyond that. • Max document size 200 KB. Max 20 open proposals per key. • A proposal identical to the current head is rejected as no_change.

Validation Validation is Ledger's quality gate, and it is fully deterministic. The same validator runs on agent proposals, human saves, imports and the validate tool.

Rules

Behavior • Errors block proposals and saves. Warnings show on the review screen and in the editor, but don't block. • Every error carries field or line, a code, a plain message and a hint with the likely fix. • Validation is pure: a function of the content, the type schemas and the space's current documents. Unit-test it heavily. • Editing a type schema re-validates nothing retroactively. Existing documents stay valid as written; they are checked on their next change. Rendering checks are warnings in the body, so a broken diagram never blocks a finding: chart_invalid (fails the Vega-Lite schema or uses a disallowed data source), math_invalid, embed_broken, and mermaid_invalid. Chart and math checks run on the server; Mermaid checks run in the editor and on the review screen.

Measurement layer Metrics come straight from merged experiment frontmatter; nothing is entered twice. When an experiment with status: concluded merges, each results value becomes a metric point.

Metric point

If a concluded experiment is later edited, its points are replaced by the new revision's values. History keeps the old values.

Metrics screen

1. Pickers: eval (defaults to the space's default eval), then metric.
2. Over time chart: x is experiment date, y is the metric. Points are colored by harness version and connected per version. The eval's baseline is a dashed line. Hover shows the experiment title, value and sample size; click opens it.
3. Harness comparison table: one row per harness version with n, mean, median, best, latest, and delta vs baseline. Deltas are green or red according to the metric's better direction.
4. Compare two versions: pick A and B; see every metric side by side with deltas.

Comparability rules • Results from different eval versions never share a chart line. Changing an eval's method means bumping its version, and the chart splits. • Experiments with verdict inconclusive still plot, drawn hollow. Abandoned experiments produce no points. • v1 shows descriptive numbers only: n, mean, median, min, max. No significance tests; the sample size is always visible so small-n results read as weak.

Setting up Memento The first session seeds the space with one harness document per distinct setup found in existing artifacts, one eval per repeatable test, and one experiment per recorded run. The metrics each eval tracks are defined by you when writing the eval files. The screens stay useful before seeding is complete: one eval and three experiments are enough for a first chart.

Auth, permissions and sharing Humans sign in with sessions; agents use scoped API keys or OAuth grants. The two never mix: an agent key can't open the web app, and a browser session can't propose on an agent's behalf.

Human sign-in • Better Auth (or Auth.js) with GitHub OAuth, Google OAuth and email magic link. No passwords. • Database sessions in httpOnly, Secure, SameSite=Lax cookies. 30-day rolling expiry. • CSRF protection on all mutations; every server action checks membership and role server-side.

Roles per space

Agent keys • Created in Settings → Agent keys by owners and editors. Each key has a label ("Cursor · MacBook"), a scope (read or propose) and an owning user. • Format lk__<32 random chars>. Shown once; stored as a SHA-256 hash plus a visible prefix. • Keys show last used time and proposal count. Revoking takes effect immediately. • A key can never merge, edit directly, archive, manage members or read another space.

OAuth grants • Every OAuth connection appears in Settings → Agents next to API keys, labeled by client and user, e.g. "Muse · Sebastian". • Each shows its space, scopes, last used time and proposal count. Revoking kills its tokens immediately. • Proposals from OAuth grants carry the same agent glyph and label as key-based agents, so the review screen never hides where a change came from.

Sharing • Invite by email with a role; invites expire after 7 days. • Optional public read-only link per space, off by default. Public views never show proposals, keys or members. • Every privileged action writes an audit event: merges, rejects, role changes, key creation and revocation.

Security basics • Rendered Markdown is sanitized; HTML is limited to the safe subset listed in Markdown capabilities. • Uploaded assets are served from signed URLs. • All secrets live in environment variables; no keys in client code.

Architecture and data model One Next.js app on Vercel, one Postgres database, one blob store. No queues, no workers, no separate MCP service in v1.

Stack

Data model users (id, email, name, avatar_url, created_at) spaces (id, slug, name, public_read bool, created_at) memberships (space_id, user_id, role, created_at)

documents (id, space_id, path, slug, type, title, head_revision_id, archived_at, created_at, updated_at) revisions (id, document_id, parent_revision_id, content text, frontmatter jsonb, content_hash, version int null, message, author_user_id, agent_key_id null, proposal_id null, created_at) proposals (id, space_id, document_id null, action, path, base_revision_id null, content text, edits jsonb null, summary, rationale, status, validation jsonb, agent_key_id null, author_user_id, reviewer_user_id null, review_note, reviewed_at, merged_revision_id null, created_at, updated_at) drafts (document_id, user_id, content, updated_at)

agent_keys (id, space_id, owner_user_id, label, scope, key_prefix, key_hash, last_used_at, revoked_at, created_at) links (from_document_id, to_slug, to_version null, in_frontmatter bool, field null) metric_points(id, space_id, experiment_document_id, revision_id, eval_slug, eval_version, metric_key, value numeric, harness_slug, harness_version, date, environment, sample_size, verdict) assets (id, space_id, path, blob_url, mime, bytes, created_at) audit_events (id, space_id, actor_user_id, agent_key_id, action, target, data jsonb, created_at)

Invariants

1. Revisions are immutable and store full content. Text is small; full snapshots keep reads and diffs simple.
2. Only two paths create revisions: a human save and a merge. Both run the validator.
3. documents.head_revision_id moves inside the same transaction that creates the revision.
4. links and metric_points are derived data. They can be rebuilt from revisions at any time with one script.
5. Documents are archived, never deleted.
6. Version lookups (slug@7) find the first revision of that document whose version column equals 7.

Code structure app/ (app)/[space]/… # screens api/mcp/route.ts # MCP server api/v1/… # REST mirror lib/ markdown/ # parse, render, links, diff schema/ # load type files → Zod validate/ # pure validator + rule tests proposals/ # create, merge, rebase metrics/ # derive points, queries auth/ # sessions, roles, key checks db/ # Drizzle schema, queries The MCP route, REST routes and server actions all call the same functions in lib/. There is one implementation of every operation.

Search, import and export Your data is always a folder of Markdown away. Search is keyword-based and fast; import and export use the exact file format.

Search • ⌘K opens one palette for documents, commands and filters. • Full-text over title, body and frontmatter values, ranked by title match, then recency. • Filters typed inline: type:experiment status:concluded harness:memento-journal@7 verdict:refuted after:2026-09-01. • Results show type icon, title, path and a snippet with matches highlighted. Under 100 ms for spaces up to 10,000 documents.

Import • Drag a folder or a .zip of Markdown files onto Settings → Import, or onto the sidebar. • Each file is validated. Valid files become documents with one initial revision each, authored "Import". Invalid files are listed with errors and a Download report button; nothing partial is saved per file. • Files without frontmatter import as type: doc with the file name as title. • Converting Claude artifacts or HTML is an agent's job: it reads them, writes typed Markdown and submits proposals. This keeps interpretation out of the product.

Export • Settings → Export downloads a .zip of the whole space as its folder of Markdown files, including .ledger/ and assets/. Re-importing it recreates the space. • Optional per-document history export: one file per revision under .history/.

Backup • Neon point-in-time restore covers the database. • v1.1: a nightly job pushes the space as Markdown to a private GitHub repo, one commit per night. This is a backup mirror, never an input.

Design language The feel is Cursor: dark-first, dense, quiet, fast. The content is the interface; chrome gets out of the way.

Foundations

Interaction rules • Everything reachable by keyboard; every list navigable with J and K. • Prefer inline editing and side panels over modals. The only modals are confirmations for irreversible actions. • Agent authorship is always visible: a small agent glyph plus key label on proposals, revisions and timeline rows. • Status is a colored dot plus a word, never color alone. • Loading states are skeletons of the real layout; optimistic updates for merge and reject.

Keyboard shortcuts

Build plan The minimum useful loop is milestones 1–4: about four and a half focused days, and enough to start logging Memento experiments. Everything after can wait until Memento is in the App Store.

Acceptance criteria

Milestones 1–4 (the loop) [ ] From Cursor, "log this experiment to Ledger" produces a valid proposal with no manual fixes, using only MCP tools. [ ] An invalid proposal returns structured errors, and the agent's retry succeeds. [ ] The proposal appears in the Inbox within 2 seconds. [ ] Merging creates a revision, updates the document and marks the proposal merged for get_proposal. [ ] An agent key cannot merge, and a revoked key is refused immediately. [ ] get_context returns under 6k tokens for a space with 100 experiments. [ ] Claude and Muse connect by pasting the MCP URL, signing in and approving scopes, with no key copied by hand. [ ] OAuth grants appear in Settings → Agents, and revoking one blocks its next call. [ ] No OAuth scope or tool allows merging, editing directly or deleting.

Milestone 5 (metrics) [ ] Merging a concluded experiment adds its points to the chart without a reload. [ ] Two harness versions on the same eval show as separate colored series with correct deltas. [ ] Bumping an eval version splits the chart.

Milestones 6–7 (the product) [ ] Editing and saving an untouched document produces an empty diff. [ ] Exporting and re-importing a space yields identical files. [ ] Every screen is usable with the keyboard alone. [ ] Review of a typical experiment proposal takes under two minutes. [ ] A test document using every syntax in Markdown capabilities renders identically in view, editor preview and review. [ ] A metrics-backed chart embedded in a finding updates after a new experiment merges.

First week of use

1. Seed the Memento space: space.md, agents.md, the current harness and its prior versions, and the evals you run.
2. Have an agent convert existing Memento artifacts into experiments, submitted as proposals, and review them in batches.
3. From then on, log every run through Ledger and check Metrics before each harness decision.

Risks and open questions The biggest risk is time: this project competes with shipping Memento. The build plan front-loads the loop so everything after milestone 4 can pause without loss.

Risks

Open questions [ ] Final product name. "Ledger" is a placeholder. [ ] Should humans with editor role also go through proposals, for a stricter record? v1 says no. [ ] Do experiments need a run log attachment (raw outputs, traces) in v1, or are assets enough? [ ] Which evals define Memento's launch bar, and what are their metrics and baselines? [ ] Should get_context be configurable per space, e.g. which sections to include? [ ] Confirm this side project has no overlap with day-job agreements before sharing it publicly.