Agent Memory MCP

git clone https://github.com/jthiruveedula/agent-memory-mcp.git
cd agent-memory-mcp
npm install
npm run build
node dist/index.js

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

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

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

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

{
  "tool": "remember",
  "arguments": {
    "content": "I prefer flat error handling over throwing.",
    "type": "preference",
    "scope": "user"
  }
}

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

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

{
  "tool": "remember_correction",
  "arguments": {
    "original_content": "I prefer flat error handling.",
    "correction_text": "Actually, I prefer Result<T, E> types.",
    "context": "Rust project"
  }
}

{
  "tool": "reflect",
  "arguments": {}
}

AGENT_MEMORY_LOG_LEVEL=debug node dist/index.js

rm -f ~/.agent-memory-mcp/memories.db ~/.agent-memory-mcp/memories.db-*

export OPENAI_API_KEY=sk-...
npm run build && node dist/index.js

|———-|———|————-| | AGENT_MEMORY_DIR | ~/.agent-memory-mcp | Where the SQLite database lives | | AGENT_MEMORY_LOG_LEVEL | info | debug, info, warn, error | | OPENAI_API_KEY | — | Optional; enables OpenAI text-embedding-3-small | | OPENAI_EMBEDDING_MODEL | text-embedding-3-small | Which OpenAI embedding model to use | | ANTHROPIC_API_KEY | — | Optional; enables Anthropic-based reflections |

Set them before launching the server, for example:

export AGENT_MEMORY_DIR="$HOME/.agent-memory-mcp"
export AGENT_MEMORY_LOG_LEVEL=debug

Core workflow

1. Store a preference

Ask your assistant to remember a preference:

“Remember that I prefer concise answers with bullets.”

Or call the tool directly:

{
  "tool": "remember",
  "arguments": {
    "content": "I prefer concise answers with bullets.",
    "type": "preference",
    "scope": "user"
  }
}

2. Log a tool outcome

After a tool call, log whether it succeeded and how expensive it was:

{
  "tool": "remember_tool_outcome",
  "arguments": {
    "tool_name": "web_search",
    "task_summary": "Search MCP specification",
    "success": true,
    "duration_ms": 850,
    "tokens_used": 1200
  }
}

3. Recall relevant context

When starting a new task, recall what you have already learned:

{
  "tool": "recall",
  "arguments": {
    "query": "concise answers",
    "limit": 5,
    "min_confidence": 0.5
  }
}

4. Correct outdated memories

If a memory is wrong, correct it:

{
  "tool": "remember_correction",
  "arguments": {
    "original_content": "I prefer concise answers with bullets.",
    "correction_text": "Actually, I prefer short paragraphs over bullets.",
    "context": "README editing"
  }
}

5. Reflect periodically

Run reflection to merge duplicates and surface insights:

{
  "tool": "reflect"
}

Tool reference

Resources and prompts

The server exposes three resources and one prompt that MCP clients can pull:

• memory://preferences — all learned preferences as JSON.
• memory://recent — recent memories as JSON.
• memory://stats — database statistics as JSON.
• memory-context prompt — injects relevant memories and preferences for a task.

Best practices

1. Scope intentionally
   • user — global across all workspaces.
   • repo — tied to a specific repository.
   • session — short-lived, tied to a conversation.

2. Be specific in recall queries — short, topic-focused queries return better results than vague ones.

3. Log tool outcomes after every meaningful tool call — the recommender improves as it accumulates success/duration/token data.

4. Apply corrections promptly — corrections update confidence and extract preferences automatically.

5. Run reflect daily or after large batches of memories — it keeps the database clean and surfaces useful insights.

6. Back up the database — copy ~/.agent-memory-mcp/memories.db and its -wal/-shm files to another location.

Troubleshooting

Server fails to start

npm run build
node dist/index.js

Check the log level with AGENT_MEMORY_LOG_LEVEL=debug.

SQLITE_MISMATCH or schema errors

The server now uses schema versioning. If you have a very old database, stop the server and delete the database files:

rm -f ~/.agent-memory-mcp/memories.db ~/.agent-memory-mcp/memories.db-*

Then restart.

Assistant cannot find tools

• Ensure the MCP config points to the absolute path of dist/index.js.
• Restart the assistant / editor after editing the config.
• Check that npm run build produced dist/index.js.

Recall returns unrelated results

• Use repo_path or scope filters.
• Raise min_confidence to filter out weak memories.
• Apply corrections to bad memories so their confidence drops.

Large database

Run reflect to merge duplicates and consider deleting old session scoped memories.

Next steps

• Read the README
• Run the test suites: npm test
• Explore the code in src/

Last updated: July 14, 2026