sessionmem

sessionmem

85.6% fewer tokens. Every session starts knowing your codebase. Stored entirely on your machine.

New session. Claude starts fresh.

WITHOUT sessionmem:
 You explain the stack. The JWT bug from last week.
 The Stripe migration that's halfway done. The billing code to stay away from.
 Same questions. Different day.

WITH sessionmem:
 [warning] JWT blacklist must be checked before issuing new tokens. Fixed PR #47.
 [decision] Stripe migration ~50% done. Do NOT use /lib/billing-v1.
 [fact] Stack: TypeScript, Next.js, Postgres.

 Claude: "Looks like you're mid-Stripe migration. Where do you want to pick up?"

sessionmem is an MCP server that watches your coding sessions and stores what actually mattered -- decisions, warnings, things that would bite you if Claude forgot them. At the start of each new session it injects the relevant bits automatically. Works with Claude Code, Cursor, Cline, Codex, Windsurf, and anything that speaks MCP.

Everything stays on your machine. No account, no cloud, no data leaving your computer unless you explicitly turn that on.

Table of Contents

• What problem does this solve?

• How is sessionmem different?

• Benchmark results

• How it works (in plain English)

• CLI command reference

• Privacy, secrets, and your data

• Memory rot: keeping memory accurate over time

• Team mode (optional)

• Cloud summarization (optional, off by default)

• Supported tools

• Further documentation

• Troubleshooting

• FAQ

• Contributing

• License

What problem does this solve?

If you've used an AI coding assistant for more than a day, you've probably hit this:

You spend twenty minutes explaining your project's setup, the libraries you use, a tricky bug you already fixed, and a decision you made about how authentication should work. The assistant nods along, helps you out... and then in your next session, it has forgotten all of it. You explain everything again.

This happens because most AI assistants only "know" what's inside the current conversation. Once that conversation ends, the context is gone.

sessionmem fixes this by sitting quietly between your assistant and your project:

• While you work, it captures what happens in the session.

• When the session ends, it summarizes the important parts (decisions made, warnings, useful facts) into short, durable notes.

• The next time you start a session, it reminds the assistant of the most relevant notes, automatically, in a small amount of text.

You don't run any of these steps yourself. Once installed, it just works in the background.

How is sessionmem different?

There are other "memory for Claude" projects out there (for example, tools like claude-mem and similar community projects). Here's what sets sessionmem apart:

sessionmem Typical cloud/Claude-only memory tools Where is data stored? A single SQLite file on your computer (~/.sessionmem/memories.db) Often a hosted service, a cloud vector database, or a separate server process you have to run Account / sign-up required? No, never Sometimes Which AI tools does it work with? Claude Code, Cursor, Codex, Cline, Windsurf, Antigravity, QCoder, and any other MCP-compatible host Usually just one specific tool (commonly Claude Code only) Secret redaction Built in, on by default. API keys, tokens, passwords, and private keys are scrubbed before anything is saved. Often not handled, or left to the user Token budget control Injected memories are trimmed to a small, fixed token budget so they don't bloat every conversation (see benchmarks below) Varies, often unbounded Old/stale memory cleanup Built-in retention policy automatically prunes old memories (configurable, on by default) Often grows forever ("memory rot") Team sharing Optional, via a shared folder you already control (network drive, synced directory). No server needed. Usually requires a shared hosted backend Offline-capable Yes, fully. Works with no network connection by default. Usually requires network access to the memory service

In short: sessionmem is the boring, local, "just a SQLite file" option: easy to inspect, back up, and delete, with no lock-in to any one vendor's AI tool.

Benchmark results

These numbers come from npm run benchmark (scripts/benchmark.mjs), which runs the real production retrieval and injection code over a fixed, synthetic set of test data with no network calls. The results are fully reproducible. See docs/benchmark.md for the full report and how to regenerate it.

Token savings

~85.6% reduction in tokens compared to carrying full session history.

Tokens Full session history (baseline) 1,587 What sessionmem injects at the start of your next session 228

In practice: instead of re-reading (or re-explaining) about 1,600 tokens of past context every session, the assistant gets a 230-token summary of just the things that matter: decisions, warnings, and key facts.

Retrieval accuracy

100% hit-rate: every one of the 10 test queries successfully retrieved the memory it was supposed to.

Metric Result Hit-rate (10 curated queries) 100.0% Recall 100.0% Precision 33.3%

Precision of 33.3% is expected here: each query retrieves the top 3 candidate memories, and only one of those three is the "expected" match for a given test query. The other two are still relevant context for the agent, just not the one being scored. The important number is recall/hit-rate: the right memory is never missed.

These benchmarks are deterministic and reproducible. Run them yourself:

npm run build # benchmark imports the compiled code from dist/
npm run benchmark # regenerates docs/benchmark.md

How it works (in plain English)

 ┌──────────────────────────────────────────────┐
 │ Your AI tool │
 │ (Claude Code, Cursor, Codex, Cline, ...) │
 └───────────────────────┬──────────────────────┘
 │
 ┌───────────▼───────────┐ ┌──────────────┐
 │ sessionmem adapter │ │ sessionmem │
 │ (translates for your │ │ CLI │
 │ specific AI tool) │ │ (you type │
 └───────────┬───────────┘ │ commands) │
 │ └──────┬───────┘
 ▼ │
 ┌──────────────────────────────────────────────┐
 │ sessionmem core engine │
 │ watches sessions · writes summaries · │
 │ finds relevant memories · trims to fit │
 └───────────────────────┬──────────────────────┘
 │
 ▼
 ┌──────────────────────────────────────────────┐
 │ One SQLite file on your computer │
 │ ~/.sessionmem/memories.db │
 └──────────────────────────────────────────────┘

• Adapters are small pieces that know how to talk to each specific AI tool. This is why sessionmem can support many tools: adding a new one doesn't change how memory itself works.

• The core engine is the same no matter which tool you use. It decides what's worth remembering, how relevant it is later, and how much of it fits in a small "reminder" at the start of your next session.

• The database is just a file. You can back it up, move it, inspect it, or delete it like any other file on your computer.

For a deeper technical dive, see docs/architecture.md.

CLI command reference

Command What it does sessionmem install Register sessionmem with the current MCP host and write default config. sessionmem uninstall [--purge] Remove sessionmem from the host. --purge also deletes the local database. sessionmem run Start the MCP server. sessionmem ping Check server connectivity. sessionmem search <query> [--limit <n>] Search memories by semantic query. sessionmem list List all memories for the current project. sessionmem show <id> Show full details of a memory. sessionmem forget <id> [--force] Delete a memory by ID. sessionmem export [path] Export memories to a JSON file. sessionmem import <path> [--merge] Import memories from a JSON file. sessionmem stats Show memory statistics for the current project. sessionmem savings [--json] Show token savings from compression and injection, with percentage. sessionmem redact-scan [--apply] Scan stored memories for secrets; --apply redacts in place. sessionmem retention prune [--force] [--days <n>] Prune old memories (dry-run by default). sessionmem config get <key> / config set <key> <value> Read and write policy config. sessionmem team enable <path> / team disable / team status Manage shared-path team memory mode. sessionmem sync Push local memories and pull teammate memories via the shared path.

Privacy, secrets, and your data

Everything stays on your machine by default. No account, no telemetry, no hosted memory service. Storage, retrieval, and summarization all run locally, governed by ~/.sessionmem/config.json.

Secrets are scrubbed automatically

Before anything is saved, sessionmem automatically removes common secret patterns and replaces them with REDACTED:

• Email addresses

• API keys (sk-..., AWS AKIA..., GitHub ghp_.../gho_..., etc.)

• Bearer tokens and JWTs

• Private key blocks (-----BEGIN ... PRIVATE KEY-----)

• Connection-string style secrets (password=..., secret=...)

This is on by default. You can scan and clean up older memories at any time:

sessionmem redact-scan # see what would be redacted
sessionmem redact-scan --apply # actually redact in place

Full details: docs/privacy-and-retention.md.

Memory rot: keeping memory accurate over time

"Memory rot" is what happens when a memory system keeps accumulating notes forever. Eventually it fills up with outdated decisions, duplicate facts, and noise, and the assistant starts surfacing stale information instead of helpful information.

sessionmem is designed to avoid this in a few ways:

Retention pruning: memories older than a configurable window (default 90 days) are automatically eligible for cleanup. This runs as a light check at the end of every session, and can also be run manually:

sessionmem retention prune # dry run - shows what *would* be deleted
sessionmem retention prune --force # actually deletes

Importance-weighted ranking: when memories are retrieved, they're ranked by a blend of semantic relevance, recency, and importance. Old, low-importance notes naturally sink to the bottom and stop being surfaced even before they're pruned.

Token-budgeted injection: only the top-ranked, most relevant memories are injected (trimmed to a small token budget, see benchmarks ), so even a large memory store doesn't produce bloated, noisy context.

Conflict resolution in team mode: when memories are merged from teammates, the system uses last-write-wins by id (so stale duplicates don't pile up) while preserving the higher importance score (so a critical warning doesn't get silently downgraded).

The retrieval benchmark above (100% hit-rate / 100% recall) demonstrates that even with the ranking and trimming in place, the right memory still surfaces. Accuracy is not traded away for compactness.

You're always in control: export everything first if you want a permanent record before pruning:

sessionmem export

Team mode (optional)

Want your whole team's AI assistants to share decisions and warnings? Point sessionmem at a shared folder (a network drive, a synced directory, or any location everyone can read and write):

sessionmem team enable 
sessionmem sync

• Off by default: nothing is shared until you turn it on.

• No server needed. It's just files in a folder you already control.

• Teammates' memories show up with an author: prefix so you know where they came from.

• Secrets are re-redacted on every pulled memory, so a teammate's snapshot can't reintroduce something your redaction policy would have stripped.

Full details, including the trust model: docs/team-mode.md.

Cloud summarization (optional, off by default)

By default, summarization (turning a session into a short memory) happens entirely locally, with no API calls.

If you explicitly opt in (allowCloudSummarization=true) and provide an ANTHROPIC_API_KEY, summarization can use Claude's API for higher-quality summaries. If that ever fails, it automatically falls back to local summarization. Your sessions are never left unsummarized.

Details: docs/cloud-summarization.md.

Supported tools

sessionmem works with any MCP-compatible host, including:

• Claude Code

• Cursor

• Codex

• Cline

• Windsurf

• Antigravity

• QCoder

...and any other tool that implements the Model Context Protocol.

Further documentation

• Architecture: how the core engine, adapters, CLI, and SQLite storage fit together.

• Benchmark: full token-reduction and retrieval-accuracy report, and how to reproduce it.

• Privacy and retention: secret redaction, retention pruning, and config.

• Team mode: shared-path team memory.

• Cloud summarization: the opt-in cloud summarization path.

• Migration: the SQLite migration system and version-upgrade policy.

• Troubleshooting: install failures, adapter issues, and better-sqlite3 native-build problems.

Contributing

Issues and pull requests are welcome. The codebase is TypeScript, tested with Vitest, and linted with ESLint:

npm install
npm run build
npm test
npm run lint

MCP config for local development: Copy .mcp.json.example to .mcp.json for local dev, or use sessionmem install to auto-configure. The .mcp.json file is gitignored because it contains machine-specific paths.

License

MIT

Quickstart

No programming experience needed. You just need a terminal (Command Prompt, Terminal, or PowerShell) and Node.js installed.

1. Install sessionmem

npm install -g sessionmem

2. Register it with your AI tool

Run this inside the project folder you're working on, with your AI tool (Claude Code, Cursor, etc.) configured:

sessionmem install

This does three things:

• Tells your AI tool's MCP host about sessionmem so it can be launched automatically.

• Creates a config file at ~/.sessionmem/config.json with safe, privacy-respecting defaults, but only if one doesn't already exist.

• Injects instructions into ~/.claude/CLAUDE.md so Claude Code knows about sessionmem's tools and uses them proactively (idempotent, so safe to re-run).

3. Start using your AI tool as normal

sessionmem run

(Most of the time you won't run this yourself. Your AI tool's host starts it automatically once it's registered.)

That's it. From here:

• sessionmem watches your sessions in the background.

• At the end of each session, it writes down a short summary of what mattered.

• At the start of your next session, it quietly reminds your assistant of the relevant bits.

You can verify everything is working with:

sessionmem ping

Troubleshooting

Run into trouble installing or running sessionmem? Start with docs/troubleshooting.md. It covers install failures, adapter-specific issues, and native module (better-sqlite3) build problems on different platforms.

Quick checks:

sessionmem ping # is the server reachable?
sessionmem stats # is data being stored?

FAQ

How do I give Cursor, Cline, or Windsurf memory between sessions? Install sessionmem (npm i -g sessionmem), then run sessionmem install in your project. It registers as an MCP server with any supported host automatically.

How do I give Claude Code persistent memory? Same install. sessionmem also ships as a Claude Code plugin (the .claude-plugin file in the repo), so it works with Claude Code's native plugin system too.

Is there a local MCP memory server that works offline with no API key? Yes. sessionmem stores everything in a single SQLite file at ~/.sessionmem/memories.db and works fully offline by default. Nothing leaves your machine unless you explicitly enable the optional cloud summarization path.

How is sessionmem different from claude-mem? sessionmem is not Claude-only. It works with Cursor, Cline, Codex, Windsurf, Antigravity, QCoder, and any other MCP host, not just Claude Code. It also redacts secrets (API keys, tokens, JWTs) by default, prunes stale memory automatically, and ships reproducible benchmarks you can run yourself.

Does sessionmem send my code to the cloud? No. Nothing leaves your machine by default. The optional cloud summarization path is opt-in and off by default.

How do I see how many tokens sessionmem saved me? Run sessionmem savings to see a breakdown of storage compression (raw session tokens vs memory tokens) and injection efficiency. Add --json for machine-readable output.