Agent Memory MCP

A self-improving agent memory server implementing the Model Context Protocol (MCP). It captures, organizes, and shares memories across all your workspaces and repositories, builds a personal knowledge graph, learns your preferences, and recommends the right tools to limit token usage.

Features

• Cross-workspace memory sharing — memories stored in ~/.agent-memory-mcp/ are available to every workspace/repo.
• Semantic + keyword recall — SQLite FTS5 full-text search plus lightweight vector similarity.
• Knowledge graph — auto-extracts entities and relations from memories, like a personal CodeGraph.
• Continuous correction — corrections are linked to memories and used to update confidence and generate preferences.
• Preference learning — learns style, formatting, workflow, and tool-selection preferences from interactions.
• Tool recommender — logs tool outcomes and recommends the best tool given a task description.
• Self-improvement — reflect analyzes patterns, merges duplicates, surfaces insights, and updates preferences.

Quick start

npm install
npm run build
node dist/index.js

📖 Full usage guide: https://jthiruveedula.github.io/agent-memory-mcp/

Platform Setup

VS Code (GitHub Copilot)

The .vscode/mcp.json is pre-configured for this workspace. Copilot will automatically discover it.

Claude Code CLI

Add the following to .claude/settings.json (already included in this repo):

{
  "mcpServers": {
    "agent-memory": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

Claude Desktop

Open ~/Library/Application Support/Claude/settings.json and add:

{
  "mcpServers": {
    "agent-memory": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/agent-memory-mcp/dist/index.js"]
    }
  }
}

Replace the path with the actual absolute path to this project.

Cursor

The .cursor/mcp.json is pre-configured for this workspace. Cursor will discover it automatically.

OpenCode

The opencode.json is pre-configured for this workspace. OpenCode will discover it automatically.

Environment variables

Variable	Description
AGENT_MEMORY_DIR	Storage directory (default: ~/.agent-memory-mcp)
AGENT_MEMORY_LOG_LEVEL	debug, info, warn, error (default: info)
OPENAI_API_KEY	Optional: enables OpenAI text-embedding-3-small embeddings
ANTHROPIC_API_KEY	Optional: enables Anthropic API-based reflections

Available tools

• remember — store a memory, correction, preference, or tool outcome.
• recall — search memories semantically and by keyword.
• recall_recent — list the most recently accessed or created memories.
• remember_correction — store a correction tied to an existing memory.
• remember_tool_outcome — log success/failure, tokens, duration for a tool call.
• get_preferences — retrieve learned preferences, optionally filtered by key prefix.
• set_preference — manually set a preference.
• get_tool_recommendations — get ranked tool recommendations for a task.
• get_knowledge_graph — explore entities and relations around a topic.
• reflect — run self-improvement analysis.
• update_memory_confidence — reinforce or penalize a memory.

Example workflow

After connecting the server to your MCP client, it will start learning as you work:

1. Store a preference

   { "tool": "remember", "content": "I prefer flat error handling over throwing." }
   

2. Log a tool outcome

   { "tool": "remember_tool_outcome",
     "arguments": { "tool_name": "grep_search", "task_summary": "Find helper usages", "success": true, "duration_ms": 120, "tokens_used": 200 } }
   

3. Recall when needed

   { "tool": "recall", "arguments": { "query": "error handling preference", "limit": 5 } }
   

4. Run reflection periodically

   { "tool": "reflect" }
   

The server also exposes a memory-context prompt and three resources (memory://preferences, memory://recent, memory://stats) that MCP clients can pull into context.

Architecture

src/
├── index.ts              # Entry point: starts MCP stdio server
├── server.ts             # MCP Server wiring (tools, resources, prompts)
├── config.ts             # Configuration and paths
├── types.ts              # Shared types and Zod schemas
├── db/
│   ├── schema.ts         # SQLite schema with versioned migrations
│   ├── embeddings.ts     # Local hash-based or OpenAI embeddings
│   └── memory-store.ts   # CRUD, search, embeddings, graph persistence
├── graph/
│   └── knowledge-graph.ts # Entity/relation extraction and graph queries
├── learning/
│   ├── preference-learner.ts  # Preference extraction and updates
│   ├── tool-recommender.ts    # Tool outcome learning
│   └── self-improver.ts       # Reflection and consolidation
└── tools/
    └── memory-tools.ts   # MCP tool handlers

Development

npm run dev        # run with tsx
npm run build      # compile TypeScript
npm run inspector  # test with MCP inspector

Testing

npm test           # runs full-test + stress-test + platform-check

# Individual suites
bash scripts/smoke-test.sh
bash scripts/full-test.sh
bash scripts/stress-test.sh
bash scripts/platform-check.sh

A GitHub Actions CI workflow is included under .github/workflows/ci.yml. Last updated: July 14, 2026.

License

MIT