project-memory-mcp

Coding agents forget everything between sessions. You explain a decision on Monday, and on Wednesday the agent re-derives it, differently. This is a small MCP server that gives agents a place to write things down and find them again — per project, across sessions, across tools.

It does three things and nothing else:

• memory_record — save a note, decision, requirement, or learning.

• memory_search — full-text search over what was saved for a project.

• project_status — see whether a project has any memory yet, counts by kind, and the last few entries.

Everything lives in one SQLite file on your machine. No cloud, no accounts, no native dependencies — it uses the node:sqlite module that ships with Node, so pnpm install pulls in only the MCP SDK and zod.

How it works

Each tool call takes an absolute project_root. That path is the project's identity: the first time a memory is recorded for a root, a project row is created; after that every search and status call is scoped to it. Two projects can contain the same words and never see each other's memories.

Memory is append-only. Recording the same kind, title, and body twice stores it once and tells you created: false. There is no update or delete — to change a decision, record a new one with supersedes pointing at the old id; the old memory keeps its history but drops out of search results. That keeps the history honest and the tool surface tiny.

Search is deliberately boring: every word in your query must appear in a hit (title, body, or tags), ranked by SQLite's FTS5 with titles weighted highest, and the last word is a prefix match so sqlite finds sqlite3. Hits come back with a short excerpt, not the full body — pass include_body: true when you need the whole text. No query syntax to learn, no way to break it with punctuation.

Related MCP server: LumenCore

Getting started

Requires Node 26 and pnpm.

pnpm install
pnpm test
pnpm build

Then point your agent harness at the built server. For Claude Code, Codex, or anything else that reads an MCP config:

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

The database is created on first use at ~/.local/share/project-memory/store.sqlite (or under $XDG_DATA_HOME if set). To put it somewhere else, set PROJECT_MEMORY_DB=/path/to/file.sqlite in the server's environment.

Teaching the agent to use it

Exposing tools is not the same as an agent knowing when to use them. skills/project-memory/SKILL.md is a short, harness-agnostic skill that tells the agent to resolve the project root once, check project_status before starting, search before re-deriving old decisions, and record requirements and decisions as they happen. Copy that folder into your harness's skills directory (for example ~/.claude/skills/ or ~/.codex/skills/) and adjust the server path in its setup section.

Kinds of memory

Project layout

src/server.ts        stdio entry point
src/mcp.ts           the three tool definitions
src/store.ts         record / search / status against SQLite
src/db.ts            schema, pragmas, database location
src/project-root.ts  validates and canonicalizes project_root
test/                vitest: store behavior and MCP round-trips
skills/project-memory/SKILL.md

License

MIT