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.

Related MCP server: Jarvis Markdown MCP

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):

• 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 }
}

The MCP tools (16)

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

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.