AI Long-Term Memory MCP Server

A Model Context Protocol (MCP) server that provides persistent long-term memory for AI agents. Designed for real-world use with Claude Code, enabling AI systems to remember across sessions.

Features

• Layered Memory Architecture: 3-layer system (facts → experiences → decision chains)

• Semantic Search: Embedding-based retrieval using cosine similarity

• Memory Decay: Activation-based decay — memories that get recalled stay alive, unused ones fade

• Emotion-Aware: Stores emotional valence and intensity, enabling "flashbulb memory" effects

• Auto-Surface: Hook-based automatic memory retrieval triggered by conversation context

• Deduplication: Automatically merges similar memories (>80% similarity threshold)

Architecture

┌─────────────────────────────────────────┐
│              Claude Code                │
│         (or any MCP client)             │
├─────────────────────────────────────────┤
│            MCP Protocol                 │
├─────────────────────────────────────────┤
│          Memory MCP Server              │
│  ┌───────────┐  ┌──────────────────┐   │
│  │  Write /   │  │  Surface /       │   │
│  │  Update /  │  │  Search /        │   │
│  │  Delete    │  │  Read            │   │
│  └─────┬─────┘  └────────┬─────────┘   │
│        │                 │              │
│  ┌─────▼─────────────────▼─────────┐   │
│  │         SQLite Database          │   │
│  │  memories + embeddings + decay   │   │
│  └─────────────────────────────────┘   │
├─────────────────────────────────────────┤
│         Auto-Surface Hook              │
│  (keyword matching on user input)      │
└─────────────────────────────────────────┘

Memory Schema

MCP Tools

Decay Mechanism

Memories decay based on last_activated, not created_at. A memory that keeps getting recalled stays active indefinitely. Decay thresholds:

• Low importance (1-2) + not activated in 7 days → decay

• Medium importance (3) + not activated in 14 days → decay

• High importance (4-5) + not activated in 30 days → decay

• Pinned memories never decay

Inspired by research on human memory consolidation — informed by 8 papers (see design doc).

Auto-Surface Hook

auto_surface.cjs runs as a Claude Code UserPromptSubmit hook. On each user message, it:

1. Extracts keywords from the message

2. Searches the memory database for matches

3. Injects relevant memories into the conversation context

This enables passive recall without explicit search commands.

Setup

npm install

Add to Claude Code MCP config:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["path/to/memory-mcp/index.js"]
    }
  }
}

Design Decisions

• SQLite over vector DB: Simpler deployment, single file, good enough for <10K memories

• Activation-based decay over time-based: Mimics human memory — used memories strengthen, unused ones fade

• Embedding dedup: Prevents memory bloat from repeated similar events

• Layered architecture: Separates facts (stable) from experiences (contextual) from decisions (actionable)

Research References

Built on research from 8 papers:

• Generative Agents (Stanford, 2023): Memory stream, reflection, planning/react

• MemGPT (2023): Tiered memory with OS-inspired page management

• LUFY (2024): Forgetting mechanism with emotion arousal weighting

• MemoRAG (2024): Memory-inspired retrieval with dual scoring

• Mem0 (2024): Graph-based memory with auto-extraction and dedup

• A-Mem (2024): Self-organizing agentic memory networks

• LoCoMo (2024): Long-context conversation memory benchmark

• Chloe/Noah (Community): Four-dimensional companion AI memory

See docs/design.md for detailed analysis of each paper's influence.

Status

In active daily use. 95+ memories across 17 sessions. Iterating based on real-world usage patterns.

License

MIT