{
  "markdown": "# memory-mcp-lite\n\nA small, opinionated memory server for AI coding assistants (Windsurf, Cursor, Claude Desktop — anything that speaks MCP).\n\nIt 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.\n\n## Why this exists\n\nMost 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.\n\nmemory-mcp-lite is that place. It stores:\n\n- technical decisions and the reasoning behind them,\n- project architecture and conventions,\n- commands, env notes, links, and gotchas,\n- task state so you can resume work later,\n- rolled-up summaries at the global / project / task level.\n\nIt 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.\n\n## How it's organised\n\nMemory lives in a tree:\n\n```\nglobal\n└── project\n    ├── [project_summary]\n    └── task\n        ├── [task_summary]\n        └── atomic  // decision | fact | gotcha | command | link | convention\n```\n\nOn 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.\n\nThe retrieval side is built to be cheap. The server's instructions push agents through three stages, from least to most expensive:\n\n```\nStage 1 — summaries              get_global_summary / get_project_summary / get_task_summary\n        │\n        ▼ (only if summaries aren't enough)\nStage 2 — FTS5 light search      search_memory_light → compact candidates\n        │\n        ▼ (only for the 1–3 most relevant hits)\nStage 3 — full detail            get_memory_detail\n```\n\nIn 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.\n\n## Stack\n\n- TypeScript, Node ≥ 20\n- Drizzle ORM over libSQL (`@libsql/client`)\n- SQLite FTS5 for lexical search\n- A closure table for efficient subtree traversal\n- The MCP TypeScript SDK (`@modelcontextprotocol/sdk`)\n\nYou can point it at a local file, a remote libSQL instance, or a Turso database — they all work the same.\n\n## Install\n\nThe fast path is to let your MCP client fetch the package via `npx`.\n\n**Windsurf** — `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory-mcp-lite\": {\n      \"command\": \"npx\",\n      \"args\": [\"memory-mcp-lite\"]\n    }\n  }\n}\n```\n\n**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory-mcp-lite\": {\n      \"command\": \"npx\",\n      \"args\": [\"memory-mcp-lite\"]\n    }\n  }\n}\n```\n\nSame pattern for any other MCP-compatible client; only the config file path changes.\n\n### From source\n\n```bash\nnpm install\nnpm run build    # outputs dist/index.js; the schema is created on first run\n```\n\nThen point your client at the compiled bundle:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory-mcp-lite\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/memory-mcp-lite/dist/index.js\"]\n    }\n  }\n}\n```\n\nIf you want to iterate on the code without a build step, `tsx` works:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory-mcp-lite\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/absolute/path/to/memory-mcp-lite/apps/server/src/index.ts\"]\n    }\n  }\n}\n```\n\n### Where the data lives\n\nBy default: `~/.memory-mcp/memory.db`. Override it with any of:\n\n| Env var                  | Purpose                                    |\n| ------------------------ | ------------------------------------------ |\n| `MEMORY_DB_PATH`         | Full path or `libsql://…` / `file:` URL.   |\n| `MEMORY_DATA_DIR`        | Directory; the file is still `memory.db`.  |\n| `DATABASE_URL`           | Accepted for backwards compatibility.      |\n| `MEMORY_DB_AUTH_TOKEN`   | Bearer token for remote libSQL / Turso.    |\n\nSo running against Turso is just:\n\n```bash\nMEMORY_DB_PATH=\"libsql://your-db.turso.io\" \\\nMEMORY_DB_AUTH_TOKEN=\"eyJhbGci...\" \\\nnpm run dev\n```\n\n## Tools\n\nNine 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.\n\n| Tool                     | Reach for it when…                                      |\n| ------------------------ | ------------------------------------------------------- |\n| `get_global_summary`     | recurring preferences, cross-project conventions        |\n| `get_project_summary`    | architecture, key decisions, long-term project context  |\n| `get_task_summary`       | resuming a specific piece of work                       |\n| `search_memory_light`    | summaries aren't enough; you want compact candidates    |\n| `get_memory_detail`      | you've picked a candidate and need the full body        |\n| `remember_decision`      | an architecture choice, trade-off, or rejected path     |\n| `remember_fact`          | a command, env note, gotcha, link, or convention        |\n| `upsert_project_summary` | after an arch change or new convention worth recording  |\n| `upsert_task_summary`    | after progress, blockers, or a plan change              |\n\nThe retrieval discipline the server asks agents to follow:\n\n1. summaries first,\n2. light search only if summaries aren't enough,\n3. full detail for at most 1–3 hits,\n4. never dump every memory just because you can.\n\n## Project identity\n\nProjects are looked up in this priority order:\n\n1. **Normalised git remote URL** — the most stable; survives directory moves and clones.\n2. **Git root path** — used when there's no remote.\n3. **Normalised workspace path** — the fallback.\n\nThis 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.\n\n## Development\n\n```bash\nnpm run typecheck      # TypeScript\nnpm run lint           # oxlint\nnpm run test           # vitest\nnpm run build          # esbuild bundle to dist/\nnpm run dev            # tsx watch\nnpm run db:studio      # Drizzle Studio for poking at the DB\nnpm run db:generate    # generate migration SQL when the schema changes\n```\n\nThe 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.\n\n## Roadmap\n\n- Optional semantic fallback (local embeddings, feature-flagged).\n- Node archival / cleanup for long-lived projects.\n- Shared-team memory, once there's a good story for auth.\n",
  "bytes": 7233,
  "sha": "6f573179f5b9e0240627f8c22bb77762f30d00fc25640e187f60c27a006f8069",
  "repo_slug": "thuupx/memory-mcp-lite",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thuupx_memory_mcp_lite_94638ee2/readme"
}