How do I use Long-Term Memory?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Long-Term Memory save that my favorite color is blue" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Long-Term Memory

by ihwooMil

Overview Schema Source Related Servers Discussions Admin

Python

Local

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:

Problem	How we solve it
Manual retrieval — you must ask "do you remember X?"	`auto_search` runs every turn, injecting relevant memories automatically
Missed memories — AI decides what to save, so experiences/stories get lost	Every turn is auto-logged; sleep cycle extracts what the AI missed
Token waste — entire memory dump inserted into context	Multi-resolution composer selects top-K memories within a token budget

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)

Tool	Description
`auto_search`	Auto-retrieve relevant memories at turn start (multi-resolution context)
`memory_save`	Save a new memory with keywords, category, and relations
`memory_search`	Semantic similarity search
`memory_update`	Update content or keywords of an existing memory
`memory_delete`	Delete a memory (respects immutability)
`memory_get_related`	BFS graph traversal for related memories
`memory_pin` / `memory_unpin`	Protect memories from forgetting
`memory_stats`	Total count and category breakdown
`memory_visualize`	Generate interactive graph HTML
`sleep_cycle_run`	Trigger maintenance (extraction + consolidation + forgetting + checkpoint)
`policy_status`	RL policy state (epsilon, action distribution, updates)
`policy_decide`	Ask the RL policy for a SAVE/SKIP/RETRIEVE decision with reasoning

Configuration

All settings via environment variables:

Variable	Default	Description
`AIMEMORY_DB_PATH`	`./memory_db`	ChromaDB persistence directory (use absolute path to ensure all components share the same DB)
`AIMEMORY_LANGUAGE`	`ko`	Language for pattern matching (`ko` / `en`)
`AIMEMORY_EMBEDDING_MODEL`	`intfloat/multilingual-e5-small`	Sentence-transformer model
`AIMEMORY_LOG_LEVEL`	`INFO`	Logging level
`AIMEMORY_ENHANCED_POLICY`	`0`	Enable 778d enhanced RL policy (`1` to enable)
`AIMEMORY_GRAPH_RAG`	`0`	Enable GraphRAG hybrid retrieval (`1` to enable)
`AIMEMORY_LIVE_HOST`	`127.0.0.1`	Live graph server host (for event push)
`AIMEMORY_LIVE_PORT`	`8765`	Live graph server port (for event push)

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.

Available Tools

13 tools

auto_searchA

Automatically retrieve and compose relevant memories for a user message.

Searches the memory store, selects the most relevant memories, and composes them into a context string within the token budget using multi-resolution levels (full text, summary, entity triple).

This tool should be called at the beginning of every conversation turn to inject relevant memory context.

Args: user_message: The user's current message to find relevant memories for. token_budget: Maximum tokens for the composed context (default: 1024). top_k: Number of memories to retrieve (default: 10, use higher values like 100 for memory review).

Inputs: user_message (required), top_k, token_budget. Returns: result

memory_deleteA

Delete a memory from the knowledge graph.

Cannot delete immutable memories. Automatically cleans up graph edges.

Args: memory_id: The ID of the memory to delete.

Inputs: memory_id (required). Returns: result

memory_get_relatedA

Get memories related to a given memory via graph edges (BFS traversal).

Args: memory_id: The starting memory ID. depth: How many hops to traverse (default: 1, max: 3).

Inputs: memory_id (required), depth. Returns: result

memory_pinA

Pin a memory to protect it from the forgetting pipeline.

Args: memory_id: The ID of the memory to pin.

Inputs: memory_id (required). Returns: result

memory_saveA

Save a new memory to the knowledge graph.

Args: content: The memory content to save (Korean or English text). keywords: Optional list of keywords. Auto-extracted if not provided. category: Memory category. One of: fact, preference, experience, emotion, technical, core_principle. Defaults to "auto" which auto-classifies from content. related_ids: Optional list of memory IDs to link as related. immutable: If True, memory cannot be updated or deleted. pinned: If True, memory is protected from the forgetting pipeline.

Inputs: content (required), pinned, category, keywords, +2 more. Returns: result

memory_searchA

Search memories by semantic similarity.

Args: query: Search query text (Korean or English). top_k: Number of results to return (default: 5, max: 200). category: Optional category filter (fact/preference/experience/emotion/technical/core_principle).

Inputs: query (required), top_k, category. Returns: result

memory_statsA

Get statistics about the memory store: total count and category breakdown.

Inputs: no named parameters. Returns: result

memory_unpinA

Remove pin protection from a memory, allowing it to be forgotten over time.

Args: memory_id: The ID of the memory to unpin.

Inputs: memory_id (required). Returns: result

memory_updateA

Update an existing memory's content and/or keywords.

Args: memory_id: The ID of the memory to update. content: New content text (optional, keeps existing if not provided). keywords: New keywords list (optional, keeps existing if not provided).

Inputs: memory_id (required), content, keywords. Returns: result

memory_visualizeB

Generate an interactive HTML visualization of the memory graph.

Creates a browser-viewable graph showing memory nodes, relationships, and knowledge graph entity triples. Requires the 'viz' extra to be installed.

Args: output_path: Optional output file path for the HTML. Defaults to data/visualizations/. include_inactive: If True, include inactive (forgotten) memories in the graph.

Inputs: output_path, include_inactive. Returns: result

policy_decideA

Ask the RL policy to decide what memory action to take for a user message.

Returns the policy's decision (SAVE/SKIP/RETRIEVE) with reasoning. If SAVE: also returns the saved memory entry. If RETRIEVE: also returns retrieved memories.

Args: user_message: The user's message to evaluate. turn_id: Optional turn identifier.

Inputs: user_message (required), turn_id. Returns: result

policy_statusA

Get the current status of the memory policy (RL bandit model).

Returns epsilon (exploration rate), recent action distribution, and total update count.

Inputs: no named parameters. Returns: result

sleep_cycle_runA

Run the memory sleep cycle.

Performs consolidation, resolution regeneration, forgetting, and checkpoint saving.

This performs periodic memory maintenance. Recommended to run periodically (e.g., daily or after many conversations).

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-09-07 03:10 across 13 tools

Disambiguation4/5

Most tools have distinct purposes, but memory_search and auto_search overlap in retrieval functionality; descriptions clarify the difference (direct search vs. automatic composition), preventing major confusion.

Naming Consistency3/5

The majority use the memory_ prefix, but sleep_cycle_run, policy_status, policy_decide, and auto_search break the pattern. The naming is readable but not consistently structured.

Tool Count4/5

13 tools is a reasonable size for a full-featured memory system, covering CRUD, search, pinning, stats, visualization, policy, and maintenance. Not excessive, though a few could potentially be consolidated.

Completeness4/5

The toolset covers core memory operations well, including save, update, delete, search, related memories, pin/unpin, stats, and visualization. A notable gap is lack of a direct get-memory-by-ID operation, but this is mitigated by search and related-memory retrieval.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

Brainbox
dev.thexi
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Knowledge & Memory AI & Machine Learning
2
https://brainbox-mcp.thexi.dev/mcp
WorkingMemoryA
ai.workingmemory
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Knowledge & Memory Search
42
https://app.workingmemory.ai/mcp
khiveA
ai.khive
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Knowledge & Memory Project Management
22134
https://khive.ai/v1/mcp
Engram
app.getengram
Persistent, verbatim, searchable memory for AI assistants — one memory across every MCP client.
Knowledge & Memory AI & Machine Learning
122
https://mcp.getengram.app/mcp

Related MCP Servers

Cognio
Knowledge & Memory RAG Systems
0xReLogic
A
license
Not graded
quality
D
maintenance
Persistent semantic memory server for AI assistants via MCP, enabling long-term context retention and semantic search across conversations.
Updated 10 months ago (2026-01-18 18:04 UTC)
12
MIT
my-memory-mcp
Knowledge & Memory Autonomous Agents
moontmsai
F
license
Not graded
quality
D
maintenance
A MCP server that provides persistent memory for AI assistants, storing personal information, relationships, and observations to enable personalized and contextual conversations.
Updated a year ago (2025-07-07 08:03 UTC)
4
-
axiom-memory
Knowledge & Memory Autonomous Agents
mungaibriankariuki-collab
A
license
Not graded
quality
C
maintenance
Persistent memory infrastructure for AI agents, enabling cross-session recall and autonomous memory evolution via an MCP server.
Updated 4 months ago (2026-07-06 19:24 UTC)
1
MIT
Selti
Knowledge & Memory RAG Systems Vector Databases
Dek1m
F
license
Not graded
quality
B
maintenance
A persistent memory server for AI agents using MCP protocol, enabling semantic storage and retrieval of dialogues, documents, and agent states.
Updated 2 months ago (2026-09-28 08:20 UTC)
-

Long-Term Memory

Why Long-Term Memory?

Key Features

Quick Start (2 minutes)

1. Install

2. Setup client instructions

3. Connect to OpenClaw

4. Connect to Claude Desktop

5. Connect to Claude Code

Live Graph Visualization

MCP Tools (13)

Configuration

Architecture

Development

Migrating from mcp-memory-server

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Cognio

my-memory-mcp

axiom-memory

Selti