memory-mcp

A local MCP server that manages an agent's long-term memory. Memory is treated not as something to "store and retrieve" but as a lifecycle in which it is born, recalled, amended, judged, and sinks.

Core idea

An agent's memories are of two kinds. Memories with ground truth (such as code indexes) can rely on hash synchronization, but assertion memories without ground truth — user utterances, decisions, and lessons — need state, version, confidence, and a verdict gate. memory-mcp combines the two with a dual structure:

• source — human-readable markdown files managed with git (<store>/memories/*.md, frontmatter metadata). Lifecycle state, supersede chains, and confidence live here.

• derivatives — a SQLite index (FTS, ranking, conflict ledger). It can be discarded at any time and rebuilt entirely from the source with a single memory_reindex call.

Designed by analyzing three sources (evidence trails in §12 of docs/design/architecture.md):

Related MCP server: cardloom-mcp

How it works

remember ──► active ◄─────────── 본문 수정 시 자동 복귀
               │ supersede 되면 자동
               ▼
            archived ──forget(deprecate, reason 필수)──► deprecated
               │                                            │
               └────────── forget(purge, confirm 필수) ──────┘
                            (파일 삭제 — git 이력이 백스톱)

• Conflict gate: when memory_remember detects neighboring memories, it returns the verdict material (shared entity, time gap, latest_wins_eligible) in the response. The verdict belongs to the calling agent (and the user) — no automatic overwrite without a verdict. Surfaced pairs are recorded by pair-hash so they are not presented again.

• Weathering: old, unused memories are not deleted but sink in the ranking — score = text × trust × state × (1 + freshness + heat). When memory_status proposes aging episodes as compaction candidates, the agent summarizes them into a knowledge memory and supersedes the originals.

• reconcile: no daemon. At the entry of every tool invocation, a stat-gate (mtime + size) → sha256 → only the changed parts are reindexed. Manually edited files also converge on the next invocation. If the body of an archived memory is edited directly, it automatically returns to active (latest intent wins).

• Korean search: without embeddings, a query planner combines word FTS (prefixes absorb postpositional variants) + trigram FTS (phrases) + a LIKE fallback for unterminated 2-char or smaller queries. So "보안을 끄는" ↔ "보안을 끄고" match.

• Honesty: recall/status always report index freshness, unparseable files, and unresolved conflicts. A lack of report ≠ completeness.

Tools (7)

Installation

Node ≥ 22.5 (node:sqlite built-in — no external native dependencies).

pnpm install && pnpm build

Register via Claude Code:

claude mcp add memory-mcp -- node /path/to/memory-mcp/dist/main.js

Or via .mcp.json:

{
  "mcpServers": {
    "memory-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/main.js"],
      "env": { "MEMORY_MCP_ROOT": "/path/to/your/store" }
    }
  }
}

The default store is ~/.memory-mcp/default (replace with the MEMORY_MCP_ROOT env var, or per-store invocation). If you manage the store in git, the git history becomes the backstop for purge.

Memory file format

---
id: 01JD2K3A9FZQ4W8XVBH5T6N7RM
type: fact | preference | decision | episode | reference | knowledge
state: active | archived | deprecated
trust: user-stated | agent-inferred | imported
entities: [ads-genisys, pacing]
source: "2026-08-24 세션, 사용자 교정"
created: 2026-08-24T14:03:00Z
updated: 2026-08-24T14:03:00Z
review_after: 2026-11-01
---
# 제목 한 줄

본문. 첫 문단이 recall 발췌로 쓰인다.

Adding a <store>/dictionary.md normalizes entity notation (- 정식명: 설명 (aka: 동의어, 약어)).

Development

pnpm typecheck   # tsc --noEmit
pnpm test        # node --test (29 tests)
pnpm lint        # biome
pnpm build       # dist/

Documentation

• Design: docs/design/architecture.md — principles, state machine, source → decision trace table

• Analysis: codebase-memory-mcp hands-on · Codebase-Memory paper · MemOS paper

License

MIT