claude-memory-extension

A zero-dependency MCP server that gives Claude instances (Cowork, Claude Code, Claude Desktop, …) persistent, shared, file-based memory across sessions.

Memories are plain markdown files on disk, grouped into bins — one directory per project or topic. The connecting Claude instance chooses its own bin (a short kebab-case slug), so different instances working on the same project converge on the same memory. Each memory file uses the same frontmatter convention as Claude Code's built-in per-project memory:

---
name: short-kebab-slug
description: one-line summary used for recall
metadata:
  type: user | feedback | project | reference
---

The fact itself, with [[links]] to related memories.

The server's MCP instructions are generated at connect time and embed a live index of every bin and memory (filename, last-modified date, one-line summary from the frontmatter description or first line), followed by terse rules: read relevant bins before re-deriving work, capture at the moment of discovery, never store mutable state or secrets, tag provenance, re-verify before high-stakes use, and fix wrong entries immediately. A connecting instance starts every session already seeing what exists, without extra prompting.

Storage

Default root: ~/.claude/cowork-memory/<bin>/<file>.md Override with the CLAUDE_MEMORY_ROOT environment variable.

Everything is plain markdown — inspect, edit, or version it with normal tools.

Tools

Tool	Purpose
list_bins	Return the current full index (bins, files, dates, summaries)
list_memories	List a bin's files with created/updated dates and frontmatter descriptions
read_memory	Read one file
search_memory	Case-insensitive literal search across all bins (or one), compact bin/file:line output
write_memory	Create/overwrite a file; creates the bin if needed
append_memory	Append text to a file without resending its content (cheap index updates)
delete_memory	Remove an obsolete or wrong memory

Bin and file names are validated against [A-Za-z0-9._-] slugs; path traversal is rejected.

Setup

Requires Node ≥ 18. No install step — the server is a single file.

Claude Code:

claude mcp add --scope user memory -- node /home/deprekated/Projects/home/claude-memory-extension/server.mjs

Cowork / Claude Desktop (or anything using the standard MCP JSON config), add under mcpServers:

{
  "memory": {
    "command": "node",
    "args": ["/home/deprekated/Projects/home/claude-memory-extension/server.mjs"]
  }
}

Smoke test

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_bins","arguments":{}}}' \
  | node server.mjs