aimem

A local-first MCP (Model Context Protocol) memory server that gives Claude Code, Cursor, Windsurf, and any other MCP-compatible AI coding assistant persistent, project-scoped memory across chat sessions.

aimem solves AI memory loss in long coding sessions: no more re-explaining your architecture, credentials, or past decisions every time you start a new chat. It's an offline, zero-API-key alternative to cloud-based AI memory services — SQLite + local vector search (sqlite-vec) + a bundled embedding model, stored inside each project's own .aimem/ folder. No external database, no cloud API, no account required. Everything runs on your machine and never leaves it.

Status: v0.2.1 — published on npm as aimem-mcp. Core functionality, reliability hardening, hybrid search, stale-fact invalidation, and the local inspection CLI are all complete and tested (Phases 1–9). Cross-client validation and real-world daily use are in progress. See CHANGELOG.md for release notes and docs/knowledge/setup/current-project-state.md for the exact current state.

Why

Long AI coding sessions eventually hit the same wall: the context window fills up, older details get dropped or summarized away, and you end up re-explaining the same architecture, credentials, and decisions over and over — in the same session, and every time you start a new one. Bigger context windows push the problem back but never solve it; they still cost tokens, still degrade reasoning as they fill, and still forget eventually.

aimem treats this as a memory architecture problem, not a context size problem. Instead of cramming everything into the context window, an aimem-connected agent stores what actually matters — credentials, decisions, architecture facts, bug fixes — in a small local database, and retrieves only what's relevant, when it's relevant.

Related MCP server: persistent-kb-mcp

How it works

┌───────────────────────────────────────────────────────────────────────────┐
│                          Developer's Local Machine                        │
│                                                                             │
│  ┌───────────────────────┐                                                │
│  │   AI Client Process    │                                                │
│  │  (Claude Code, Cursor, │                                                │
│  │   Windsurf, Claude     │                                                │
│  │   Desktop, Gemini CLI, │                                                │
│  │   Codex, ...)          │                                                │
│  └───────────┬────────────┘                                                │
│              │  MCP protocol (JSON-RPC 2.0 over stdio)                     │
│              ▼                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                     aimem MCP Server (Node.js/TS)                    │  │
│  │   Tool Router → Capture Engine → Conflict/Versioning Engine          │  │
│  │              ↘ Retrieval Engine ↗                                    │  │
│  │                    Storage Engine ←→ Embedding/Search Engine         │  │
│  └────────────────────┬────────────────────────────────────────────────┘  │
│                       ▼                                                    │
│         <project_root>/.aimem/memory.db  (SQLite + sqlite-vec, WAL mode)   │
│         local ONNX embedding model, bundled at install — no API key       │
│                                                                             │
│      Nothing above ever leaves the machine. No network calls at runtime.  │
└─────────────────────────────────────────────────────────────────────────┘

Memory is captured three ways, all driven by the AI's own judgment rather than a background process:

• Event-based — the moment the AI notices something worth remembering (a credential, a decision, a bug fix), it's stored immediately.

• Turn-count based — a periodic safety-net scan every ~10–15 exchanges catches anything the event trigger missed.

• Context-threshold based — as the AI senses its own context window filling up, it runs one last thorough save before older messages get dropped.

At the start of every new chat, the AI always checks whether memory exists for the project and asks where to pick up — it never silently stays quiet, and never dumps the entire memory store into context at once.

See docs/architecture/system-overview.md for the full component breakdown and docs/architecture/data-flow.md for sequence diagrams of every operation.

Tools

Full request/response schemas: docs/architecture/api-design.md.

Inspecting memory from the terminal

aimem-inspect is a second, independent binary — a human-facing local CLI for looking at .aimem/memory.db directly, with no AI client involved:

cd your-project
aimem-inspect list                       # every entity and its current observations, as JSON
aimem-inspect search "staging database"  # the same hybrid search memory_search uses
aimem-inspect export                     # full graph as JSON (including invalidated facts) — for backup/migration
aimem-inspect repair --yes               # restore from the rolling backup after corruption

It's installed automatically alongside the MCP server — no separate step. repair refuses to do anything if the live database already passes its own integrity check (even with --yes), and only restores from the backup once the live file is genuinely broken, a valid backup exists, and --yes is passed — see docs/knowledge/setup/usage-guide.md for the exact flow.

Design principles

• Local-first, always. Memory lives in <project_root>/.aimem/memory.db — a single portable SQLite file that moves with the project, survives renames, and is gitignored by default.

• Zero external dependencies. No Docker, no database server, no cloud API, no mandatory API key. The embedding model is bundled into the npm package at install time.

• Project-scoped, not global. Each project's memory is fully isolated. There's no cross-project or organization-wide memory in v1 — that's an explicit, deliberate scope boundary.

• Never silently overwrite. If new information contradicts something already stored, aimem flags the conflict and asks for confirmation before updating — old values are archived, not deleted.

• Fail loud, never crash. A missing memory file is a normal fresh start. A corrupted one is reported with an exact, actionable error — the server never crashes the host AI client's connection.

• Recoverable, not just resilient. A rolling backup is taken before every risky write; if .aimem/memory.db is ever corrupted, aimem-inspect repair can restore it, but only with your explicit confirmation — recovery is never a decision an AI agent makes on your behalf.

The full reasoning behind every major decision — including real, non-obvious bugs found along the way (a missing shebang, a symlink-resolution bug that silently broke every real install path, an FTS5 index-backfill quirk, and a hybrid-search ranking bug caught during a pre-publish hardening pass) — is recorded in docs/decisions/ADR.md.

Installation

npm install -g aimem-mcp

Claude Code — register it once, available in every project from then on:

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

Any other MCP client (Cursor, Windsurf, Claude Desktop, ...) — add to your client's MCP config:

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

If your Node.js was installed via a version manager (nvm, fnm, volta) — MCP clients often can't find node/npx on PATH this way; use absolute paths instead. See docs/knowledge/setup/install-guide.md for the exact fix.

Full install steps, verification, and troubleshooting: docs/knowledge/setup/install-guide.md. For what actually happens once it's running — how memory gets created and used day to day — see docs/knowledge/setup/usage-guide.md.

Development

npm install            # installs dependencies and bundles the local embedding model
npm run build           # compiles TypeScript to dist/
npm test                # fast unit + integration tests (134 tests)
npm run test:coverage    # same suite, with a v8 coverage report
npm run test:e2e         # spawns the real compiled server over stdio (10 tests)
npm run lint              # ESLint

This project follows a strict phase-based development discipline documented in docs/implementation/phases.md and docs/RULES.md — every change is tracked in docs/AGENT-LOG.md, and every non-trivial decision has a corresponding entry in docs/decisions/ADR.md.

Documentation

All project documentation lives under docs/ on GitHub (not shipped inside the npm package itself, to keep install size down — the links below always point at GitHub):

License

MIT © 2026 Yogesh Joshi