aimem

Your AI coding assistant forgets. Your project shouldn't.

A local MCP memory server for Claude Code, Cursor, Windsurf, and any other MCP client. It stores what matters about this project — decisions, credentials, architecture, bug fixes — and, in v0.3.0, the raw conversation history too. Search it next session instead of re-explaining.

No account. No API key. No Docker. Nothing leaves your machine.

• Two kinds of memory, one file — curated facts (memory_search) and full raw conversation history (memory_search_history), both searchable, both local.

• Hybrid search, not just vectors — semantic similarity fused with exact-term FTS5 matching, so file paths, error strings, and identifiers actually surface.

• Runs fully offline — the embedding model is bundled at install; no API key, no account, no network call at query time.

• Works with any MCP client — Claude Code, Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI.

• Conflict-aware, not silently overwritten — a new fact that contradicts an old one asks first; nothing gets lost, just archived.

• Inspectable without an agent — aimem-inspect is a plain CLI: list, search, export, repair, no MCP client required.

Install

1. Install the package (Node.js 20.x):

npm install -g aimem-mcp

2. Connect your editor — pick one:

Claude Code (once, every project after that):

claude mcp add aimem-mcp npx aimem-mcp -s user

Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI — add to your MCP config:

{
  "mcpServers": {
    "aimem-mcp": {
      "command": "npx",
      "args": ["aimem-mcp"]
    }
  }
}

If Node was installed with nvm / fnm / volta and the tools never appear, use absolute paths — that's the most common install miss. Full steps: install guide.

Then tell the agent to prefer aimem over its own notes: agent instructions.

Related MCP server: persistent-kb-mcp

New in 0.3.0 — two kinds of memory, one file

History search is hybrid too (vector + keyword), with filters for time, role, kind (message / tool_call / event), and session. Each hit has an id — memory_get_history_item returns the full text when the 300-character summary isn't enough.

You:  "What did we decide about the auth service?"
Agent: memory_search → "JWT, 15-minute expiry, Redis for sessions."

You:  "What exact error did we hit when we first wired sqlite-vec?"
Agent: memory_search_history → the original tool result, not a paraphrase.

Why this exists

A bigger context window only postpones forgetting. Old turns get summarized away, tokens get expensive, and Monday's chat doesn't remember Friday's decision.

aimem treats that as a memory problem: keep a small local database per project, retrieve only what's relevant, never dump the whole store into the prompt.

At the start of a new chat the agent checks memory_get_project_context (including whether that summary has gone stale) and asks where to pick up. It does not stay silent, and it does not paste everything.

Day-to-day flow: usage guide.

How it works

flowchart LR
  A[Claude Code / Cursor / Windsurf] -->|MCP stdio| B[aimem]
  B --> C[Facts: store / search / conflicts]
  B --> D[History: ingest + search]
  C --> E[".aimem/memory.db"]
  D --> E
  E --> F[sqlite-vec + FTS5 + local ONNX model]

Everything in that diagram stays on your disk. The embedding model is bundled at install. There is no telemetry and no cloud call at runtime.

Architecture and sequence diagrams: system overview · data flow.

Tools

Facts

History (v0.3.0)

Schemas: API design.

Inspect it yourself

aimem-inspect is a separate CLI (installed with the package). No MCP client required:

cd your-project
aimem-inspect list                       # entities + current observations
aimem-inspect search "staging database"  # same hybrid search as memory_search
aimem-inspect export                     # full JSON, including invalidated facts
aimem-inspect repair --yes               # restore from backup only if the live DB is corrupt

repair will not overwrite a healthy database, even with --yes. History browsing from this CLI is not in 0.3.0 yet — use the two history tools from the agent for now.

Design rules that don't move

• Local-first. One SQLite file per project. Moves with the folder. Gitignored by default.

• No silent overwrite. Conflicts ask; old values are archived, not deleted.

• Fail loud, never crash the host. Missing DB = fresh start. Corrupt DB = a clear error, not a dead MCP connection.

• Recoverable. Rolling backup before risky writes; you confirm any restore.

• History is verbatim. Transcript ingest stores real messages and tool I/O, which can include secrets you pasted. Treat .aimem/ the same way you treat a .env.

Why those choices: ADR.md.

Documentation

User-facing first:

The rest of the tree — PRD, phases, modules (including history-engine), workflows, current project state — is under docs/. Docs are on GitHub only (not inside the npm tarball) so install stays smaller.

Development

npm install             # dependencies + bundled embedding model
npm run build           # TypeScript → dist/
npm test                # fast suite (298 tests)
npm run test:coverage
npm run test:e2e        # real subprocess MCP (30 tests)
npm run lint

Phase discipline: phases · RULES · AGENT-LOG.

License

MIT © 2026 Yogesh Joshi