Long-Term Memory

Persistent, self-organizing memory for AI assistants.

Drop-in MCP server that gives Claude (and any MCP client) long-term memory — powered by semantic search, knowledge graphs, and reinforcement learning.

Note: This package was previously published as mcp-memory-server. That package is deprecated — please use long-term-memory going forward.

Why Long-Term Memory?

Current AI memory tools have two critical problems:

Related MCP server: my-memory-mcp

Key Features

• RL-powered policy — Contextual bandit decides when to save, skip, or retrieve (not just keyword matching)

• Semantic search — ChromaDB + multilingual sentence-transformer embeddings (intfloat/multilingual-e5-small)

• Knowledge graph — Entity-relation graph (NetworkX) for multi-hop reasoning

• GraphRAG hybrid retrieval — Vector similarity + graph traversal, fused and re-ranked by an RL re-ranker

• Auto-linking — New memories automatically link to similar existing ones (similarity ≥ 0.92)

• Multi-resolution text — Full text → summary → entity triples, composed within token budget

• Automatic conversation logging — All turns recorded to SQLite; high-value turns instantly extracted to ChromaDB

• Sentence-level splitting — Multi-sentence turns split into individual memories with independent categories

• Sleep cycle memory extraction — Batch-processes missed memories from conversation logs using progressive RL extraction

• Auto category classification — memory_save auto-classifies content category from patterns

• Forgetting pipeline — Decay-based aging with consolidation, pinning, and immutable protection

• Sleep cycle — Periodic maintenance: extraction, dedup, compress, forget, checkpoint

• Live graph — Real-time WebSocket visualization of the memory graph

• Multilingual — Korean and English pattern support out of the box

Quick Start (2 minutes)

1. Install

pip install long-term-memory

Or with uv:

uv pip install long-term-memory

pip install long-term-memory[ko]     # Korean NLP support
pip install long-term-memory[live]   # Real-time graph visualization
pip install long-term-memory[viz]    # Static graph visualization

2. Setup client instructions

# For OpenClaw
aimemory-setup openclaw

# For Claude Code
aimemory-setup claude

This injects memory usage instructions into your client's configuration files (SOUL.md/TOOLS.md for OpenClaw, CLAUDE.md for Claude Code). Re-run anytime to update.

By default, memories are stored in ./memory_db (resolved to an absolute path at install time). To use a custom location:

# OpenClaw — sets the DB path in the extension and mcporter config
aimemory-setup openclaw --db-path /path/to/my/memory_db

# Claude Code
aimemory-setup claude --db-path /path/to/my/memory_db

# Shell script (OpenClaw)
bash scripts/install_openclaw.sh --db-path /path/to/my/memory_db

You can also set the AIMEMORY_DB_PATH environment variable, which all components respect:

export AIMEMORY_DB_PATH=/path/to/my/memory_db
aimemory-setup openclaw   # picks up the env var automatically

All components (MCP server, live viewer, OpenClaw extension) will use the same absolute path, ensuring data consistency.

3. Connect to OpenClaw

mcporter config add aimemory --command aimemory-mcp --scope home

4. Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aimemory": {
      "command": "aimemory-mcp"
    }
  }
}

That's it. Claude now has persistent memory across all conversations.

{
  "mcpServers": {
    "aimemory": {
      "command": "aimemory-mcp",
      "args": ["--with-live"]
    }
  }
}

Then open http://127.0.0.1:8765 to see the live memory graph.

{
  "mcpServers": {
    "aimemory": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/long-term-memory", "aimemory-mcp", "--with-live"],
      "env": {
        "AIMEMORY_DB_PATH": "/path/to/memory_db"
      }
    }
  }
}

5. Connect to Claude Code

claude mcp add aimemory -- aimemory-mcp

Or with live graph:

claude mcp add aimemory -- aimemory-mcp --with-live

Live Graph Visualization

Real-time WebSocket-based memory graph that updates as memories are saved, searched, or deleted.

# Option 1: auto-start with MCP server
aimemory-mcp --with-live

# Option 2: standalone server
aimemory-live --port 8765

# Option 3: standalone with custom DB path
aimemory-live --db-path /path/to/memory_db

# Option 4: via environment variable
AIMEMORY_LIVE=1 aimemory-mcp

Open http://127.0.0.1:8765 in a browser. Requires the [live] extra (pip install long-term-memory[live]). Features:

• Force-directed graph layout with category-based coloring

• New nodes glow green on save, blue on search

• Event log sidebar with hover-to-highlight (hover a log entry to highlight related nodes)

• Persistent event history across browser refreshes

• Cross-process events — MCP server pushes events to the live graph via WebSocket

MCP Tools (13)

Configuration

All settings via environment variables:

Architecture

┌─────────────────────────────────────────────────┐
│                   MCP Client                     │
│     (Claude Desktop / Claude Code / OpenClaw)    │
└────────────────────┬────────────────────────────┘
                     │ stdio (JSON-RPC)
┌────────────────────▼────────────────────────────┐
│              FastMCP Server (13 tools)           │
├──────────────────────────────────────────────────┤
│              MemoryBridge (orchestrator)          │
├──────────┬──────────┬──────────┬─────────────────┤
│ RL Policy│ Retrieval│ Storage  │ Maintenance      │
│          │          │          │                  │
│ Rule-    │ ChromaDB │ Graph    │ Sleep Cycle      │
│ Based +  │ vector + │ Memory   │ (extraction,     │
│ MLP      │ Knowledge│ Store    │  consolidation,  │
│ Bandit   │ Graph    │          │  forgetting,     │
│          │ (GraphRAG)│         │  checkpoints)    │
│ Re-ranker│          │ SQLite   │                  │
│ (11d MLP)│          │ Conv Log │ Extraction RL    │
└──────────┴──────────┴──────────┴─────────────────┘
         ↕ WebSocket (cross-process)
┌──────────────────────────────────────────────────┐
│          Live Graph Server (aimemory-live)        │
│     vis.js force-directed graph + event log      │
└──────────────────────────────────────────────────┘

Development

# Clone and install dev dependencies
git clone https://github.com/ihwooMil/long-term-memory.git
cd long-term-memory
uv sync --extra dev

# Run tests (611+ tests)
uv run pytest tests/ -q

# Lint & format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

Migrating from mcp-memory-server

pip uninstall mcp-memory-server
pip install long-term-memory

No code changes needed — the Python import name (aimemory) and CLI commands (aimemory-mcp, aimemory-viz, aimemory-live) remain the same.

License

MIT — see LICENSE for details.