Skip to main content
Glama
memory-mcp-lite

memory-mcp-lite

by thuupx

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.

Related MCP server: Mind Keg MCP

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:

Env var

Purpose

MEMORY_DB_PATH

Full path or libsql://… / file: URL.

MEMORY_DATA_DIR

Directory; the file is still memory.db.

DATABASE_URL

Accepted for backwards compatibility.

MEMORY_DB_AUTH_TOKEN

Bearer token for remote libSQL / Turso.

So running against Turso is just:

MEMORY_DB_PATH="libsql://your-db.turso.io" \
MEMORY_DB_AUTH_TOKEN="eyJhbGci..." \
npm run dev

Tools

Nine tools, all returning both a human-readable JSON block and a structuredContent object for programmatic clients. The server also ships a strict description and annotations payload for each tool so agents can pick the right one without guessing.

Tool

Reach for it when…

get_global_summary

recurring preferences, cross-project conventions

get_project_summary

architecture, key decisions, long-term project context

get_task_summary

resuming a specific piece of work

search_memory_light

summaries aren't enough; you want compact candidates

get_memory_detail

you've picked a candidate and need the full body

remember_decision

an architecture choice, trade-off, or rejected path

remember_fact

a command, env note, gotcha, link, or convention

upsert_project_summary

after an arch change or new convention worth recording

upsert_task_summary

after progress, blockers, or a plan change

The retrieval discipline the server asks agents to follow:

  1. summaries first,

  2. light search only if summaries aren't enough,

  3. full detail for at most 1–3 hits,

  4. never dump every memory just because you can.

Project identity

Projects are looked up in this priority order:

  1. Normalised git remote URL — the most stable; survives directory moves and clones.

  2. Git root path — used when there's no remote.

  3. Normalised workspace path — the fallback.

This means the same project keeps the same memory even if different clients hand you slightly different paths, and moving a repo doesn't orphan everything you've stored.

Development

npm run typecheck      # TypeScript
npm run lint           # oxlint
npm run test           # vitest
npm run build          # esbuild bundle to dist/
npm run dev            # tsx watch
npm run db:studio      # Drizzle Studio for poking at the DB
npm run db:generate    # generate migration SQL when the schema changes

The schema is defined in apps/server/src/db/schema.ts and re-asserted on every startup by ensureSchema() (see apps/server/src/db/migrate.ts). That function is also where the FTS5 virtual table and its triggers get created — Drizzle doesn't manage virtual tables, so we do it ourselves with plain SQL. It's idempotent, so there's nothing to run manually.

Roadmap

  • Optional semantic fallback (local embeddings, feature-flagged).

  • Node archival / cleanup for long-lived projects.

  • Shared-team memory, once there's a good story for auth.

Available Tools

9 tools
get_global_summaryGet global memory summaryA
Read-onlyIdempotent

Return the user's cross-project global memory summary (coding style, recurring preferences, stable workflow conventions). USE WHEN: the request depends on durable user-level preferences that apply across projects. DO NOT USE WHEN: the question is project-specific, purely syntactic, or self-contained. RETURNS: { found, summary? } where summary has { id, title, summary, updated_at }.

Inputs: no named parameters. Returns: found, summary

get_memory_detailLoad full memory detailA
Read-onlyIdempotent

Load the full body of a specific memory by id. USE WHEN: a search_memory_light candidate looks relevant and you need its full content / metadata. DO NOT USE WHEN: you have not identified a specific memory id, or you are tempted to call this many times in a row. LIMIT: call at most 3 times per user turn. RETURNS: { found, memory? } where memory has { id, title, summary, content, memory_type, level, importance, source, metadata, created_at, updated_at }.

Inputs: id (required). Returns: found, memory

get_project_summaryGet project memory summaryA
Read-onlyIdempotent

Return the concise summary for the current project (architecture, key decisions, conventions). USE WHEN: the request depends on project-level context — architecture, conventions, long-term decisions, or project overview. DO NOT USE WHEN: the request is about the current task's state, global preferences, or is self-contained. CALL ORDER: prefer this before search_memory_light. Pass workspace_path OR git_root OR remote_url OR project_id so the server can identify the project. RETURNS: { project_id, found, summary? } where summary has { id, title, summary, updated_at }.

Inputs: git_root, project_id, remote_url, workspace_path. Returns: found, summary, project_id

get_task_summaryGet task memory summaryA
Read-onlyIdempotent

Return the current task summary (what was done, blockers, next steps). USE WHEN: the user asks to continue, resume, or recall recent work on a task. DO NOT USE WHEN: there is no prior task state referenced, or the request is about global / project-level context. RETURNS: { project_id, found, summary? } where summary has { id, title, summary, updated_at }.

Inputs: task_id, git_root, project_id, remote_url, +1 more. Returns: found, summary, project_id

remember_decisionStore a technical decisionA

Persist a durable technical decision (architecture choice, trade-off, accepted pattern, rejected alternative). USE WHEN: the user confirms a decision that should outlive the current session. DO NOT USE WHEN: the info is a transient fact/command (use remember_fact) or raw chat log. IMPORTANCE: defaults to 0.8 — override only if the user signals otherwise. RETURNS: { project_id, memory_id }.

Inputs: title (required), summary (required), source, content, +5 more. Returns: memory_id, project_id

remember_factStore a fact / command / gotchaA

Persist a concise atomic memory: fact, command, gotcha, link, or convention. USE WHEN: the user gives concrete reusable info (a command, env detail, integration note, rule). DO NOT USE WHEN: the info is a major decision (use remember_decision) or a summary (use upsert_*_summary). FACT TYPES: fact | command | gotcha | link | convention | decision (prefer remember_decision for 'decision'). RETURNS: { project_id, memory_id }.

Inputs: title (required), summary (required), source, content, +6 more. Returns: memory_id, project_id

search_memory_lightSearch memories (compact candidates)A
Read-onlyIdempotent

Lexical FTS5 search across atomic memories. Returns compact candidate records only — not full content. USE WHEN: the summary tools above do not provide enough context AND the request includes a concrete search phrase (command name, symbol, past event). DO NOT USE WHEN: summaries already answer the question, the query is empty/too vague, or you only need the global/project/task summary. CALL ORDER: always call summary tools first. Then follow up this tool's top 1-3 results with get_memory_detail — never dump all candidates. RETURNS: { count, results: [{ id, title, summary, memory_type, level, importance, updated_at }] }.

Inputs: query (required), limit, scope, git_root, +3 more. Returns: count, results

upsert_project_summaryCreate or update project summaryA
Idempotent

Idempotently create or replace the structured project summary node. USE WHEN: architecture, conventions, or key decisions changed enough that a fresh summary is worth storing. DO NOT USE WHEN: the change is a single fact / decision (use remember_fact or remember_decision). RETURNS: { project_id, summary_id }.

Inputs: title (required), summary (required), git_root, project_id, +3 more. Returns: project_id, summary_id

upsert_task_summaryCreate or update task summaryA
Idempotent

Idempotently create or replace the current task summary (progress, blockers, next steps). USE WHEN: meaningful progress was made, a blocker appeared, or the plan changed and the next session must resume. DO NOT USE WHEN: the update fits better as a single fact or decision. RETURNS: { project_id, summary_id }.

Inputs: title (required), summary (required), git_root, project_id, +3 more. Returns: project_id, summary_id

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct scope or action: summaries by level (global/project/task), retrieval (search vs detail), and persistence (fact vs decision vs summary upsert). No two tools have ambiguous boundaries.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (get_*, search_*, remember_*, upsert_*). The naming is predictable and clearly conveys each tool's purpose.

    Tool Count5/5

    With 9 tools, the server covers reading (3), searching (1), retrieving (1), remembering (2), and updating (2) summaries. This is well-scoped for a lightweight memory system.

    Completeness4/5

    The tool set covers the core memory operations: read summaries at three levels, search, detail retrieval, and persist facts/decisions/summaries. Minor omission: no upsert_global_summary, but the domain is 'lite' and the gap is acceptable.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight server that provides persistent memory and context management for AI assistants using local vector storage and database, enabling efficient storage and retrieval of contextual information through semantic search and indexed retrieval.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A persistent memory server that stores and retrieves atomic coding insights like architectural decisions and debugging patterns for AI agents. It enables agents to maintain institutional knowledge across sessions using semantic search and local SQLite storage.
      22 npm
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding assistants with persistent project memory to retain architectural decisions, code patterns, and domain knowledge across sessions. It stores data locally in a SQLite database, allowing agents to remember, recall, and manage project-specific context using full-text search.
      4 npm
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Provides persistent cross-session memory and full-text search for AI coding assistants, storing project context, decisions, and preferences while enabling searchable access to conversation history via local SQLite.
      8
      1
      MIT