Relax! Memory MCP

---

Archived. Claude can now use multiple files for memories.

---

A persistent memory server for AI agents, built on the Model Context Protocol.

Why this server?

Most AI agents lose context between sessions. Built-in memory features (like Claude Code's MEMORY.md) are plain files the agent must read and write manually — they have no structure, no categories, and no way to list or search entries without reading the entire file.

Relax! Memory MCP fixes this by giving agents structured, persistent memory via tools:

• Categorised storage — memories are grouped by category (e.g. config, design, architecture), so an agent can store and retrieve related facts without scanning everything.
• Minimal token cost — list_memories returns a lightweight hierarchical index. The agent only fetches full values when it needs them, keeping context windows small.
• Upsert semantics — storing a memory with the same category + name overwrites the previous value. No duplicates, no cleanup needed.
• Instant persistence — every write is flushed to a single JSON file on disk. Survives crashes, restarts, and agent re-connections.
• Zero dependencies at runtime — just Node.js and the MCP SDK. No database, no cloud service, no API key.
• Multi-instance friendly — use --dir and --name to run separate memory stores for different projects or agents from the same binary.

Tools exposed

Tool	Description
add_memory	Store or update a memory (category, name, description, value)
get_memory	Retrieve a specific memory by category and name
delete_memory	Delete a memory by category and name
list_memories	List all memories as a hierarchical index grouped by category

Installation

npm install
npm run build

This compiles TypeScript into dist/ and makes dist/index.js the executable entry point.

Configuration

Add the server to your MCP client config. Ommit --dir for currently running project.

Claude Code (CLI)

claude mcp add --scope user memory -- node d:/installdir/dist/index.js --dir d:/my-project

Claude Desktop / Claude Code (manual)

Add to your claude_desktop_config.json or .claude.json:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": [
        "d:/src/AI/MCP/Memory/dist/index.js",
        "--name", "Project Memory",
        "--dir", "d:/my-project"
      ]
    }
  }
}

CLI flags

Flag	Default	Description
--name	Memory MCP for current project	Server name reported to the MCP client (set if you have a general server that all projects shpuld be able to access)
--description	Persistent memory storage	Server description
--dir	Current working directory	Directory where memories.json is stored

Running

Start the server directly (stdio transport):

node dist/index.js

Or with flags:

node dist/index.js --dir ./my-project --name "My Project Memory"

The server communicates over stdin/stdout using the MCP stdio transport. It is designed to be launched by an MCP client, not called directly from a browser or HTTP client.

Debugging

Run tests

npm test

Uses Vitest. Tests create temporary directories and verify the full lifecycle: add, get, update, delete, persistence, and hierarchical indexing.

Inspect the stored data

Memories are stored as plain JSON in memories.json inside the configured --dir:

cat memories.json

[
  {
    "name": "tech-stack",
    "category": "architecture",
    "description": "Chosen technology stack",
    "value": "TypeScript, PostgreSQL, OpenLayers"
  }
]

Debug with MCP Inspector

Use the MCP Inspector to interactively call tools:

npx @modelcontextprotocol/inspector node dist/index.js -- --dir .

This opens a web UI where you can invoke add_memory, list_memories, etc. and see the raw JSON responses.

Attach a Node debugger

node --inspect dist/index.js --dir .

Then open chrome://inspect in Chrome or attach from VS Code using a launch configuration:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Memory MCP",
  "program": "${workspaceFolder}/dist/index.js",
  "args": ["--dir", "."],
  "outFiles": ["${workspaceFolder}/dist/**/*.js"]
}

License

MIT