aimem

Persistent, project-scoped memory for any MCP-compatible AI coding assistant.

aimem is a local-first Model Context Protocol server that gives AI agents — Claude Code, Cursor, Windsurf, Claude Desktop, Gemini CLI, Codex, or anything else that speaks MCP — a persistent memory that survives across chat sessions. Memory lives inside each project's own .aimem/ folder: no external database, no cloud API, no account, no API key. Everything runs on your machine and never leaves it.

Status: v0.1.0 — published on npm as aimem-mcp. Core functionality complete and tested (Phases 1–7). Cross-client validation and real-world daily use are in progress. See 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.

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.

The full reasoning behind every major decision — including two real, non-obvious bugs found and fixed during packaging (a missing shebang, and a symlink-resolution bug that silently broke every real install path) — is recorded in docs/decisions/ADR.md.

Installation

npm install -g aimem-mcp

Then register aimem as an MCP server in your AI client's configuration, pointing at the installed binary. If your Node.js was installed via a version manager (nvm, fnm, volta), use an absolute path to both node and the server entry point rather than a bare aimem command — see docs/knowledge/setup/install-guide.md for why and the exact fix.

{
  "mcpServers": {
    "aimem": {
      "command": "node",
      "args": ["/absolute/path/to/aimem/dist/server.js"]
    }
  }
}

Full prerequisites, verification steps, and troubleshooting: docs/knowledge/setup/install-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
npm run test:e2e    # spawns the real compiled server over stdio
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/:

License

MIT © 2026 Yogesh Joshi