memory-manage-mcp

Your project remembers, no matter which AI agent you use.

memory-manage-mcp is a local-first, database-free persistent memory server for AI coding agents, exposed over the Model Context Protocol (MCP).

Start a task in VS Code with GitHub Copilot, continue it in Cursor, finish it with Claude Code or Gemini CLI — the next agent automatically recognizes that it is working on the same project and continues from where the previous agent stopped.

• 🗂️ Local-first — everything is stored as plain files under ~/.agent-memory/. No cloud, no API keys, no external database, no network calls.
• 🤝 Agent & IDE independent — any MCP client works: VS Code, Cursor, Claude Desktop, Claude Code, Gemini CLI, Windsurf, …
• 🔍 Project-aware — projects are identified by git remote URL (or .agent-memory.json, or path), so the same repo cloned to different machines/paths shares one memory.
• 🧠 Curated memory, not chat logs — decisions, requirements, architecture, tasks, problems, solutions and progress are stored as distilled, ranked entries.
• 🤜🤛 Structured handoffs — before an agent stops, it writes what was done, what remains, known problems and the recommended next action.
• 🛡️ Crash-safe & concurrency-safe — atomic writes (temp → fsync → rename), append-only logs, file locks.
• 🩺 CLI + doctor — inspect projects, search memory, and diagnose your setup.

---

Requirements

• Node.js >= 18
• (Optional) git on your PATH — used read-only for project detection and unfinished-work signals.

Install

# from the repository
git clone <this-repo> memory-manager-mcp
cd memory-manager-mcp
pnpm install
pnpm run build

# or install globally
pnpm add -g memory-manage-mcp   # once published

Verify the installation:

node dist/cli/index.js doctor
# Memory MCP is ready.

Auto-configure your IDEs (recommended)

One command detects every supported AI client installed on your machine and registers the memory server in each client's MCP config:

memory-manage-mcp setup            # or: node dist/cli/index.js setup

Supported clients (one dedicated registry per client):

Client	Config file(s) written
VS Code (Copilot)	%APPDATA%/Code/User/mcp.json — plus Code - Insiders and VSCodium variants (servers key, type: "stdio")
Cursor	~/.cursor/mcp.json
Claude Desktop	%APPDATA%/Claude/claude_desktop_config.json — plus Windows Store/MSIX installs (%LOCALAPPDATA%/Packages/Claude_*/LocalCache/...)
Claude Code	~/.claude.json
Antigravity	~/.gemini/config/mcp_config.json and ~/.gemini/antigravity-ide/mcp.json
Gemini CLI	~/.gemini/settings.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Codex CLI	~/.codex/config.toml (TOML [mcp_servers.manager-mcp] table)

• Only clients that are actually installed are touched; others are skipped.
• Existing config files are preserved (a .bak backup is created first) and written atomically — other MCP servers you configured stay intact.
• The server is registered under the name manager-mcp — that is the prefix you will see on its tools in your IDE (e.g. manager-mcp_save_memory). Entries left under the old memory key by earlier versions are migrated automatically on the next setup.
• Self-registering: the MCP server also registers itself silently the first time it starts, so even a bare node dist/index.js launch ends up configured everywhere. Disable with AGENT_MEMORY_NO_AUTO_SETUP=1.

Useful flags:

memory-manage-mcp setup --dry-run          # show what would change, write nothing
memory-manage-mcp setup --client cursor    # configure a single client
memory-manage-mcp setup --force            # configure even if not detected as installed
memory-manage-mcp setup --json             # machine-readable report
memory-manage-mcp uninstall                # remove the memory entry from all client configs
memory-manage-mcp uninstall --client vscode

After setup, restart your IDE/client and the 15 memory tools are available. Prefer manual configuration? See the next section.

How do I know it is working?

1. memory-manage-mcp doctor — the Client registration check lists every client where the server is registered as manager-mcp:

   ✓ Client registration   registered as "manager-mcp" in: vscode, cursor
   

2. In your IDE — after restarting, the MCP tool list should show the 15 tools prefixed with manager-mcp_ (e.g. manager-mcp_initialize_project_context, manager-mcp_save_memory).

3. Ask your agent — tell it to call initialize_project_context; a successful briefing response means the server is live and the project is registered.

Connect your AI client manually

The server speaks MCP over stdio. Point any MCP client at node <path-to>/dist/index.js (or memory-manage-mcp if installed globally).

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (workspace) or your user MCP settings:

{
  "servers": {
    "manager-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/memory-manager-mcp/dist/index.js"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "manager-mcp": {
      "command": "node",
      "args": ["C:/path/to/memory-manager-mcp/dist/index.js"]
    }
  }
}

Claude Desktop / Claude Code

claude_desktop_config.json (or claude mcp add):

{
  "mcpServers": {
    "manager-mcp": {
      "command": "node",
      "args": ["C:/path/to/memory-manager-mcp/dist/index.js"]
    }
  }
}

claude mcp add manager-mcp -- node C:/path/to/memory-manager-mcp/dist/index.js

Gemini CLI

gemini mcp add manager-mcp -- node C:/path/to/memory-manager-mcp/dist/index.js

Any other MCP client

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

Tip: run pnpm run dev during development — it starts the server from TypeScript sources via tsx.

How project detection works

When a tool receives a workspacePath (or falls back to the current directory), the project identity is derived with this priority:

1. Git remote URL — https://github.com/company/pms.git, git@github.com:company/pms.git and ssh://… all normalize to github.com/company/pms, then hash to a stable proj_… id. Same repo, any machine, any clone path → same memory.
2. .agent-memory.json — drop this file in a project root to force an identity (for non-git projects or monorepos):

   { "projectId": "my-project", "name": "My Project" }
   

3. Absolute path — last resort; memory is tied to that exact path.

Projects are auto-registered on first use — no setup step required.

Storage layout

Everything lives under ~/.agent-memory/ (override with the AGENT_MEMORY_HOME environment variable):

~/.agent-memory/
├── config.json                  # server configuration
├── projects.json                # project registry
└── projects/
    └── proj_<hash>/
        ├── project.json         # project metadata
        ├── context.json         # compact project context
        ├── memories.jsonl       # append-only memory log (versioned + tombstones)
        ├── tasks.json           # task list
        ├── decisions.json       # decision log
        ├── sessions.jsonl       # agent working sessions
        └── handoffs/
            ├── latest.json      # most recent handoff
            └── history/         # all previous handoffs

All writes are atomic (temp file → fsync → rename) or append-only with fsync; list mutations happen under a per-project lock file. Corrupt or partially-written lines are skipped gracefully on read.

Configuration

~/.agent-memory/config.json is created with defaults on first run:

{
  "maxContextItems": 20,
  "enableRawSessions": true,
  "search": { "maxResults": 20 }
}

Key	Meaning
maxContextItems	Max items per section in the generated briefing
enableRawSessions	Keep raw session records (summaries are always kept)
search.maxResults	Default result limit for search_memory

The MCP tools (16)

Tool	Purpose
initialize_project_context	Call first. Detects/registers the project and returns a compact briefing: current task, latest handoff, previous conversation digest, completed/remaining work, problems, decisions, recommended next action.
get_project_context	Lightweight fetch of the stored project context.
save_memory	Save a curated memory (decision, requirement, architecture, task, problem, solution, progress, fact, preference, constraint, discovery). Pass id to update.
get_memory	Retrieve one memory by id.
search_memory	Ranked keyword search across memories, tasks, decisions, handoffs, session summaries, conversation digests and context.
get_current_task	Most relevant open task + other open tasks.
update_task	Create or update a task (active, in_progress, completed, blocked, abandoned).
record_decision	Record an important decision (long-lived in ranking).
get_decisions	List decisions, newest first.
create_handoff	Call before stopping. Structured handoff: completed, remaining, problems, changed files, next action.
get_latest_handoff	Fetch the most recent handoff (optionally with history).
start_session	Begin tracking an agent working session.
save_session_digest	Call before stopping. Compress the ENTIRE conversation into one detailed digest (max 4000 chars); injected into the next chat's briefing.
finish_session	End a session with status + summary.
delete_project_memory	Permanently delete one project's memory (confirm: true).
clear_memory	Permanently delete all memory (confirm: true + phrase "delete everything").

Recommended agent workflow (zero-touch for the user)

The user never types memory commands — everything happens automatically behind the scenes:

1. On start → the agent calls initialize_project_context by itself. The briefing includes the previous conversation's digest, so the agent understands the last chat from first message to last. If unfinished work is detected, it asks the user once: "Would you like to continue where you left off? (yes/no)" — yes resumes from the recommended next action, no starts fresh.
2. While working → the agent silently saves decisions, requirements, problems and progress with save_memory, and tracks work with update_task.
3. Before stopping → the agent silently calls save_session_digest (compresses the whole conversation into a compact digest), then create_handoff + finish_session, so the next chat (even in another IDE) can pick up seamlessly.

A machine-readable version of this guidance lives in docs/AGENT_GUIDE.md — you can reference it from your client's rules/instructions file.

CLI

memory-manage-mcp <command> [--workspace <path>] [--json]

  projects                  List known projects
  project current           Detect the project for the current directory
  project inspect [id]      Inspect a project's stored memory
  memory search <query>     Search memory across a project
  handoff latest            Show the most recent handoff
  sessions                  List agent sessions
  doctor                    Diagnose the installation
  setup [--client <id>] [--force] [--dry-run]
                            Auto-configure installed AI clients
  uninstall [--client <id>] Remove the memory entry from client configs
  clear --all --yes         Permanently delete ALL memory

Every command has built-in help — use -h / --help after the command, or help <command>:

memory-manage-mcp --help              # overview of all commands
memory-manage-mcp help setup          # detailed help for one command
memory-manage-mcp setup --help        # same thing
memory-manage-mcp doctor -h           # short flag works too

Examples:

memory-manage-mcp doctor
memory-manage-mcp project current --workspace ./my-app
memory-manage-mcp memory search "employee permission"
memory-manage-mcp handoff latest --json

When developing from source, prefix commands with node dist/cli/index.js instead of memory-manage-mcp.

Privacy

• All data stays on your machine in ~/.agent-memory/. Nothing is ever sent anywhere.
• Raw conversation transcripts are never stored by default; only distilled memories you explicitly save.
• Delete a single project with delete_project_memory, or everything with memory-manage-mcp clear --all --yes.

Troubleshooting

Symptom	Fix
Client can't see the tools	Make sure command is an absolute path to node and args[0] is the absolute path to dist/index.js. Run pnpm run build first.
Wrong project detected	Check memory-manage-mcp project current. Add a .agent-memory.json to pin an identity, or add a git remote.
Same repo, different memory per machine	Ensure the git remote URL is set (git remote -v) — it is the primary identity.
Anything else	Run memory-manage-mcp doctor (or pnpm run doctor) and read the check list.

Development

pnpm install
pnpm run build        # compile TypeScript → dist/
pnpm run dev          # run the MCP server from sources (tsx)
pnpm run typecheck    # strict type check
pnpm test             # vitest suite (61 tests: unit + CLI + MCP stdio integration)
pnpm run test:watch

Architecture

types ─► storage (MemoryStore interface ─► FileSystemMemoryStore)
              │
git service ─►│
              ▼
project (identity / detector / registry)
              ▼
memory manager + ranker ─► search ─► context (compressor / unfinished / builder)
              ▼
service facade ─► MCP tools ─► stdio server
              └──────────────► CLI + doctor

The MemoryStore interface (src/storage/interface.ts) is the only place that touches persistence — swap in SQLite, Postgres or a cloud backend later without changing any business logic.

License

MIT — see LICENSE.