memory-mcp-lite

A small, opinionated memory server for AI coding assistants (Windsurf, Cursor, Claude Desktop — anything that speaks MCP).

It runs locally, stores durable knowledge on your disk, and tries very hard to stay out of your agent's way until you actually need it.

Why this exists

Most AI clients already have some form of short-term memory. They remember the current conversation, maybe a few rules you've set, and that's about it. What they don't give you is a place to park things that should outlive the session — the architectural decision you made last week, the one weird build command for this repo, the gotcha that bit you three times in a row.

memory-mcp-lite is that place. It stores:

• technical decisions and the reasoning behind them,
• project architecture and conventions,
• commands, env notes, links, and gotchas,
• task state so you can resume work later,
• rolled-up summaries at the global / project / task level.

It deliberately does not store raw chat transcripts, replace your client's built-in rules, run embeddings or vector search, or need a server or cloud connection.

How it's organised

Memory lives in a tree:

global
└── project
    ├── [project_summary]
    └── task
        ├── [task_summary]
        └── atomic  // decision | fact | gotcha | command | link | convention

On top of the tree you can draw optional graph-lite edges between any two nodes — related_to, depends_on, affects, caused_by, supersedes, references. Handy when one decision obsoletes another, or a gotcha only matters in the context of a specific command.

The retrieval side is built to be cheap. The server's instructions push agents through three stages, from least to most expensive:

Stage 1 — summaries              get_global_summary / get_project_summary / get_task_summary
        │
        ▼ (only if summaries aren't enough)
Stage 2 — FTS5 light search      search_memory_light → compact candidates
        │
        ▼ (only for the 1–3 most relevant hits)
Stage 3 — full detail            get_memory_detail

In practice this means your agent asks for a summary first, and only pays for the big payload when it has a specific reason to. If you skip this policy, you just end up dumping a bunch of stringly-typed JSON into context for no reason.

Stack

• TypeScript, Node ≥ 20
• Drizzle ORM over libSQL (@libsql/client)
• SQLite FTS5 for lexical search
• A closure table for efficient subtree traversal
• The MCP TypeScript SDK (@modelcontextprotocol/sdk)

You can point it at a local file, a remote libSQL instance, or a Turso database — they all work the same.

Install

The fast path is to let your MCP client fetch the package via npx.

Windsurf — ~/.codeium/windsurf/mcp_config.json:

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

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Same pattern for any other MCP-compatible client; only the config file path changes.

From source

npm install
npm run build    # outputs dist/index.js; the schema is created on first run

Then point your client at the compiled bundle:

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "node",
      "args": ["/absolute/path/to/memory-mcp-lite/dist/index.js"]
    }
  }
}

If you want to iterate on the code without a build step, tsx works:

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/memory-mcp-lite/apps/server/src/index.ts"]
    }
  }
}

Where the data lives

By default: ~/.memory-mcp/memory.db. Override it with any of:

... View full README on GitHub