thrift-memory

Thrift Memory is acost-first MCP memory server for coding agents that stop reloading largeMEMORY.md,AGENTS.md, and project context files every session.It recalls only task-relevant memory under ahard token budgetand returns a savings receipt:baselineTokens vs injectedTokens vs savedTokens.

savedTokens = baselineTokens - injectedTokens

If your coding agent re-loads the same large context file at every session start, that reload is pure, repeated token cost. Thrift Memory caps it and — uniquely — logs a receipt on every recall so you can see the token usage you avoided, not just trust that you avoided it.

Budgeted recall, in one line:Thrift Memory recalls only task-relevant memory under a hard token budget and logs a receipt showing baselineTokens vs injectedTokens vs savedTokens.

Status: early0.0.x. APIs are useful but still allowed to change beforev0.1.

- MCP manages memory recall and token receipts.
- thrift-proxymanages live request trimming and rate-limit retries.

Every recall returns a savings receipt —baselineTokens,injectedTokens,savedTokens— so you can see how many tokens you avoided. No other server in this category positions itself aroundprovingthe saving.

The closest competitor,@provos/memory-mcp-server, also recalls under a token budget — but it does not surfacewhat the budget saved you. Thrift Memory's differentiator is not "I do memory"; it is "I do memory with acost accounting." ThesavedTokens = baselineTokens - injectedTokensreceipt is the thing no one else in this category leads with.

Honest summary: if you need the smartest possible recall, use a knowledge-graph layer like Mem0 or Zep. If your coding agents keep re-paying to reload largeMEMORY.md/AGENTS.md/ project context files at every session start and you want tomeasure and cap that costwith no extra infrastructure, that gap is what Thrift Memory fills. The two are not mutually exclusive — Thrift Memory can sit in front of a heavier store as the budget/metering layer.

remember(scope, text, agentId?, sessionId?, tags?) Store a memory in org, agent, or session scope. recall(agentId, tokenBudget, task?, tags?) Return relevant memories under a hard token budget. Also returns { injectedTokens, baselineTokens, savedTokens }. search_memory(agentId, task?, tags?, limit?) Browse matching memories without applying a small recall budget.

See Your Own Waste (10 seconds, nothing installed)

Before adopting anything, measure what your agents already reload every session:

It scans the current repo for agent memory / instruction files —CLAUDE.md,CLAUDE.local.md,MEMORY.md,AGENTS.md,GEMINI.md,.cursorrules,.cursor/rules/,.windsurfrules,.clinerules,.github/copilot-instructions.md, plus your user-global~/.claude/CLAUDE.md— and prints the bill:

Thrift Memory audit — D:\myrepo File Tokens CLAUDE.md 3,000 .cursor/rules/api.mdc 900 AGENTS.md 800 .github/copilot-instructions.md 300 TOTAL reloaded per session 5,000 At 10 sessions/day (--sessions): ~50,000 tokens/day, ~1,500,000/month ≈ $22.50/month at $15/M input tokens (an assumption — adjust: --price-per-mtok) With recall capped at 2,000 tokens/session (--budget): projected saving ~60%

Every number is computed from your files with the same estimator the meter uses — nothing is phoned home, nothing is installed. Flags:--path=,--sessions=,--budget=,--price-per-mtok=.

Option A — Claude Code plugin (one command, automatic memory)

If you use Claude Code, install the whole thing — MCP server, a memory-aware agent, and/thrift-recall//thrift-remembercommands — in one step:

/plugin marketplace add YohadH/thrift-memory /plugin install thrift-memory@thrift

Automatic memory (plugin v0.2.0):the plugin ships aSessionStarthook that runsthrift-memory session-contextand injects a budgeted memory slice (default 1,500 tokens) directly into context at every sessionstart,resume,/clear, andpost-compaction. Your durable memories survive context loss with zero tool calls — and each auto-injection is metered (agentsession-start), so the dashboard shows what the automatic path costs and saves too. An empty store injects nothing.

Real end-to-end run, against this feature's own development session.Rather than only a synthetic fixture,context-watchwas replayed against the actual, live Claude Code transcript that was generatedwhile building this feature*— a genuinely long session (963 KB, 410 lines, realclaude-sonnet-5/claude-fable-5usage data, no window override). Four real snapshots were cut from that transcript at increasing points in the session's actual history and fed through the CLI in chronological order, each as a fresh hook invocation:

This matches the documented "200k window → saves at ~40% and ~80%" behavior exactly, using genuine per-turn token growth instead of hand-picked numbers. The full 963 KB transcript (well above the 64 KB bounded tail-read threshold) was also run standalone and returned in well under a second (~0.3–0.6s wall time, dominated by Node process startup, not transcript parsing) — confirming the bounded tail-read keeps the hook cheap even against a large, real, long-running session.

The proxy is optional. Use it when an agent can point its LLMbase_urlat a local HTTP gateway.

Security — run it locally only.The proxy forwards your real provider API key upstream unchanged. It binds to127.0.0.1by default (enforced in code, not just docs), so it is not reachable off-host unless you deliberately opt in with--host=0.0.0.0/THRIFT_PROXY_HOST. Never expose it on a public interface or share the port. It is a single-tenant developer tool, not a hardened multi-tenant gateway. Responses are also buffered, so SSE streaming is not passed through yet.

npx thrift-proxy \ --upstream=https://api.anthropic.com \ --host=127.0.0.1 \ --port=8787 \ --budget=4000 \ --meter-path=~/.thrift/meter.jsonl

Then configure the agent's LLM base URL ashttp://localhost:8787and keep using the real provider API key.

- trims live request context under a hard token budget,
- writes the same savings receipts as the MCP surface,
- retries upstream429and503 Retry-Afterresponses,
- throttles concurrent upstream requests per provider.

thrift-proxybuffers responses in this version; streaming passthrough is a future improvement.

The import script is generic and local-only. It can import markdown files into a JSONL store:

node scripts/import-memories.mjs \ --source=./memory \ --scope=org \ --store-path=~/.thrift/memories.jsonl \ --dry-run

For agent-scoped memories, put markdown files under project directories and use--scope=agent:

memory/ checkout-service/ dev.md qa.md docs-site/ writer.md

node scripts/import-memories.mjs --source=./memory --scope=agent

import { JsonlStore, ScopedRetriever, InMemoryMeter, ThriftMcpServer } from "thrift-memory"; const server = new ThriftMcpServer({ store: new JsonlStore({ path: "./memories.jsonl" }), retriever: new ScopedRetriever(), meter: new InMemoryMeter(), defaultTokenBudget: 2000, }); await server.runStdio();

npm install npm run typecheck npm run build npm test

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Provides perfect memory for AI-assisted development by capturing project context snapshots, enabling natural language search, evolution tracking, and code intelligence.

Your AI development companion. An MCP server that gives your AI persistent memory, structured specifications, and adaptive change management — so it builds what you actually want.

A persistent development partner that prevents context drift and maintains project memory across all development sessions.