Kronicle Lite

kronicle-lite

A local-first MCP server that tells your agent when its notes went stale.

Agents write notes, runbooks, decisions. Then the world moves: a block gets rewritten, a decision gets reversed, a procedure gets retired. Nothing in a plain memory store tells the agent. It keeps reasoning from the thing it read three sessions ago, confidently.

kronicle-lite is a small SQLite-backed document store where:

• every write is an event on a hash chain you can verify from a public genesis with sha256sum;
• every recall() hit comes with a signed receipt that later answers "is this still the current version?" — VERIFIED, SUPERSEDED (here is the new one), TOMBSTONED, or UNVERIFIED;
• get_system_state gives the agent an orient call: pass your last cursor, get exactly what changed since, a drift banner when you have been away too long, and a retraction list of things you may have relied on that are now wrong;
• every hit carries an honest label — can_act, inspect_only or never_act, with the reason — and an empty answer says what was searched, what was not, and whether the index was fresh. Secrets are refused before they reach the append-only chain.

It is one process, one file, no accounts. It runs over stdio next to Claude Code, Cursor, Claude Desktop, Codex, GitHub Copilot or any MCP client, and over loopback Streamable HTTP for clients that cannot spawn a process.

See it in one command

npx -y kronicle-lite demo

No LLM, no network, a temp dir that is removed afterwards. A runbook goes in; an agent orients and reads "Deploys go to the staging cluster stg-west-2 first."; someone changes it to stg-east-1; the agent's next orient says, before it acts:

- [behavioral] seq 9: You previously relied on "Deploys go to the staging cluster `stg-west-2` first."

(runbook › Deploy runbook › Deploy target); current truth is "Deploys go to the staging cluster stg-east-1 first." (seq 9). Reconcile before proceeding. changed: Deploys go to the staging cluster [-stg-west-2-]{+stg-east-1+} first.

Then someone edits the SQLite file by hand: recall withholds the edited text, the old receipt verifies UNVERIFIED (content_tampered), verify-chain exits 1, rebuild restores the text from the chain. A put holding an API key is refused before anything is chained, an empty recall answers absent_in_searched with the scopes it did not search, and an edit to the chain itself is caught at its seq.

0.6.0 — honest labels. Every recall hit carries

authority: can_act | inspect_only | never_act with a reason; only

block-level evidence (the block's exact text found, now, in its recorded

source file) reaches can_act; superseded, tombstoned, withheld and drifted

text never does. absence {searched, not_searched, index_fresh, verdict}

separates "searched, found nothing" from "not searched", and a stale or

cold index never certifies "not found". Hits you already read this session

rank lower (never hidden). Secrets (API keys, tokens, private keys,

connection strings) are refused on put / import / watch, or stored redacted

on request; served text is scrubbed again at read time. serve --core

serves six tools; recall caps content with a "read the whole document"

pointer. Rules: docs/HONESTY.md. All additive: no hash,

receipt, cursor or event layout changed.

0.5.0 closes the gaps an adoption audit found: what the agent reads

is now checked against the chain, not only the log (recall, verify,

verify-chain, doctor, rebuild); instruction files are keyed by

project, so two repositories sharing a data dir no longer retract each

other's rules; retractions carry the old and new words; tools/list is

71% smaller; serve --http also serves 2025-era clients such as Cursor.

Details in CHANGELOG.

0.3.0 speaks MCP 2026-07-28 (TypeScript SDK v2). Every tool has an

outputSchema and returns structuredContent; tools/list and

server/discover carry cache hints; results carry resultType. The

stdio server and (since 0.5.0) serve --http are dual-era: a client

that still opens with the 2025-era initialize handshake (2025-11-25,

2025-06-18, 2025-03-26) is served too.

0.4.0 adds off-box anchoring (checkpoint --push, verify --remote),

chained instructions (watch, retractions of kind instruction),

git-aware blocks (bind_git, STALE_SOURCE) and kronicle-lite doctor.

All additive: 0.3.0 chains verify byte-for-byte.

kronicle-lite is not a memory server. It sits beside one. Keep using

whatever you use for knowledge graphs or semantic recall; point kronicle-lite

at the notes whose staleness would hurt.

Install

Requires Node ≥ 20.

npm install -g kronicle-lite          # or run via npx, see below

kronicle-lite serve # stdio MCP server, data in ~/.kronicle-lite

Claude Code

claude mcp add kronicle-lite -- npx -y kronicle-lite serve

Optional: copy skills/orient/ to .claude/skills/orient/ and add the wake contract from examples/.claude/CLAUDE.md to your CLAUDE.md (it includes "pulse before every world-changing command"). Then typing orient re-grounds the agent against the chain. To push changes that land while the agent works, add a PostToolUse hook on kronicle-lite orient --cursor C --focus retractions --json (docs/PUSH.md). To gate world-changing commands on changes the agent has not re-read yet, add a PreToolUse hook on kronicle-lite pending --actor --json and block while pending_count > 0 (docs/PUSH.md "Pending"). For a check at the moment git push / terraform apply / kubectl apply actually runs, in any client, see exec-time pulse shims. Notes the agent writes after reading something are linked to what it read; when a source changes, the note is served never_act / stale_derived (docs/HONESTY.md §6).

Cursor

Cursor reads .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) and interpolates ${workspaceFolder}, ${userHome} and ${env:NAME} in command, args, env, url and headers:

{

"mcpServers": { "kronicle-lite": { "command": "npx", "args": ["-y", "kronicle-lite", "serve", "--actor", "cursor"] } } }

This uses the default store (~/.kronicle-lite, shared with your other clients; documents are scoped per project since 0.5.0), which is also the one the exec-time shims check. To keep a store per workspace instead, add "--data-dir", "${workspaceFolder}/.kronicle-lite": the shims (0.8.1) find a project-local .kronicle-lite/ by walking up from the repository a command acts on, but when ~/.kronicle-lite holds a store too they cannot tell which one the agent uses and refuse world-changing commands until you pin one (kronicle-lite shim install --data-dir DIR).

For the HTTP mode below use { "url": "http://127.0.0.1:7417/mcp", "headers": { "Authorization": "Bearer ${env:KRONICLE_LITE_BEARER}" } } instead of command/args. Since 0.5.0 a 2025-era HTTP client such as Cursor's is served (statelessly); before, it was refused. Source: Cursor Docs — Model Context Protocol.

Claude Desktop

claude_desktop_config.json:

{ "mcpServers": { "kronicle-lite": { "command": "npx", "args": ["-y", "kronicle-lite", "serve", "--actor", "claude-desktop"] } } }

Codex

~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.kronicle-lite]

command = "npx" args = ["-y", "kronicle-lite", "serve", "--actor", "codex"]

optional: default_tools_approval_mode = "writes" # prompt only for put/supersede/tombstone

Codex reads the server instructions at startup and uses the first 512 characters as server-wide guidance; kronicle-lite's instructions are the orient loop and fit in that window. Per OpenAI's docs the same file also takes enabled_tools / disabled_tools, startup_timeout_sec (default

1. and tool_timeout_sec (default 60). Source:

OpenAI — Model Context Protocol.

GitHub Copilot (coding agent + code review)

Repository Settings → Copilot → MCP servers (under "Code, planning, and automation"); the configuration is shared by the Copilot coding agent and Copilot code review:

{

"mcpServers": { "kronicle-lite": { "type": "local", "command": "npx", "args": ["-y", "kronicle-lite", "serve", "--data-dir", "./.kronicle-lite", "--actor", "copilot"], "tools": ["get_system_state", "audit_assumptions", "recall", "verify", "verify_chain", "anchor_status"] } } }

The store lives in the checkout (./.kronicle-lite): exec-time shims installed in the same environment find it by walking up from the repository (0.8.1), or pin it with kronicle-lite shim install --data-dir "$PWD/.kronicle-lite".

tools is required; GitHub recommends allowlisting read-only tools because the agent calls them without asking. The six above are the ones kronicle-lite marks readOnlyHint: true, which is also the set Copilot code review will use (it ignores tools without that annotation). Add put_document, supersede_block, tombstone_block (or "*") if the coding agent should write. Secrets must be named COPILOT_MCP_* and referenced from env. Source: GitHub Docs — Extending Copilot coding agent with MCP.

More in examples/.

Streamable HTTP: serve --http

For a client that cannot spawn a process (or several clients sharing one store on the same box):

kronicle-lite serve --http                       # http://127.0.0.1:7417/mcp

kronicle-lite serve --http --port 9000 # other port kronicle-lite serve --http --bearer-file ./token # token from a file you manage kronicle-lite serve --http --bearer "$TOKEN" # token from the environment

• Auth. Every request must carry Authorization: Bearer . By default the token lives in /http-bearer.token, generated on first run with mode 0600; print it with cat ~/.kronicle-lite/http-bearer.token.
• Loopback. Binds 127.0.0.1; Host and Origin are validated against loopback (DNS-rebinding defence). --host 0.0.0.0 --allow-host myhost.lan --allow-origin myhost.lan opens it up; put TLS in front.
• Stateless, both eras. No session id, GET/DELETE answer 405. A 2026-07-28 request carries its protocol version in _meta and the MCP-Protocol-Version header; a 2025-era client that opens with initialize (Cursor, most clients today) is served by a fresh server instance per request (0.5.0). --modern-only refuses those with UnsupportedProtocolVersionError (-32022), as 0.4.0 did.
• Trust domain. Single tenant: the token is the whole store. See docs/THREAT-MODEL.md.

Sixty-second tour

Works as-is in an empty directory after npm install -g kronicle-lite (data goes to ~/.kronicle-lite; add --data-dir DIR to keep it apart):

printf '# Deploy runbook\n\n## Deploy target\nDeploys go to the staging cluster `stg-west-2` first.\n' > runbook.md

store it: split into blocks, one hash-chained event per change

kronicle-lite put runbook runbook.md --title Runbook

orient as an agent would, and keep the cursor it hands back

C=$(kronicle-lite orient --actor me --json | node -pe 'JSON.parse(require("fs").readFileSync(0)).cursor_compact')

change the runbook behind the agent's back

sed -i.bak 's/stg-west-2/stg-east-1/' runbook.md kronicle-lite put runbook runbook.md --title Runbook

orient again with the cursor: the retraction says what changed, in words

kronicle-lite or