claims-mcp

claims-mcp

A small memory for agents that treats what it knows as claims that age. You assert a claim about an entity ("acme is priority #1", "the launch is on track"), each claim decays on a half-life set by how volatile it is, and the server tells you which claims have gone stale and which contradict each other.

It is a stdio MCP server plus a CLI over one local SQLite file. No network, no accounts.

Runtime: Bun. v0 uses bun:sqlite, so it runs on Bun ≥ 1.1, not plain Node. A Node build (node:sqlite) is a possible follow-up.

Model

Field	Meaning
entity	What the claim is about (free text key).
kind	priority (may carry assertedRank), status, fact, relationship.
volatility	stable (half-life 365d), slow (30d), volatile (7d).
confidence	0..1 at last confirmation. Effective confidence halves every half-life since lastConfirmed, floored at 0.05.
state	active, stale, contradicted, retired. Only active claims are checked.

A claim's identity is (entity, kind, claim): asserting it again updates it rather than duplicating.

MCP tools

Tool	Does
claim_add	Assert or update a claim.
claim_search	Case-insensitive substring search over claim text and entity.
claim_confirm	Re-confirm now: resets decay, reactivates, optionally sets confidence.
claim_retract	Retire a claim.
claims_contradictions	Conflicts among active claims: duplicate-rank (two entities claim the same priority rank), status-conflict (several active status claims for one entity). Pass observed weekly ranks to also get rank-drop: an asserted-priority entity that every signal ranks worse than rank + 2 for 3 valid periods.
claims_decayed	Active claims past a staleness threshold (default 0.5), stalest first.

Resource: claims://all (every claim as JSON).

observed is { "signals": [{ "<entity>": [rank_now, rank_1_period_ago, ...] }, ...], "validPeriods": [true, ...] }. You supply the observations (commit counts, time spent, anything you can rank); the server does not collect them.

Use

bun install

Add to an MCP client (Claude Code shown):

claude mcp add claims -- bun /path/to/claims-mcp/src/mcp.ts

The database lives at ~/.claims-mcp/claims.db; override with --db <path> or CLAIMS_MCP_DB.

CLI:

bun src/cli.ts add acme priority slow 0.8 "acme comes first" --rank 1
bun src/cli.ts search comes
bun src/cli.ts stale 0.5
bun src/cli.ts contradictions
bun src/cli.ts confirm <id>
bun src/cli.ts retract <id>

Development

bun test          # 19 tests, synthetic claims only
bun run typecheck
bun run audit     # publish gate: home paths, private names, secret patterns

Set AUDIT_TERMS="name1|name2" to add your own private names to the audit.

Provenance

Not a straight extraction. The decay curve and the rank-drop rule are ported from a personal agent memory (rank-drop now takes caller-supplied observations); the duplicate-rank and status-conflict rules are new claim-vs-claim logic written for this package. It shares no code, data or storage with the original.

Licence

MIT