MAPLE: Memory-Augmented Persistent Learning Engine

A Model Context Protocol (MCP) server that provides persistent long-term memory for AI agents. Built on a 3-agent architecture with multi-channel retrieval, automatic memory extraction, and activation-based decay. Designed for real-world daily use with Claude Code.

In active production use — 60+ memories across 30+ sessions, iterating based on real-world usage patterns.

Features

• 3-Layer Memory Architecture: Facts → Experiences → Decision Chains, with distinct decay and retrieval policies per layer

• Multi-Channel Hybrid Search: BM25 keyword matching + vector semantic similarity + entity extraction + mood detection, with configurable channel weights

• Surprise-Based Scoring: Information-gain metric that automatically prioritizes novel, high-value content for storage

• Activation-Based Decay: Memories that get recalled stay alive; unused ones fade — inspired by human memory consolidation research

• Emotion-Aware Storage: Valence, intensity, and mood tags enable "flashbulb memory" effects for emotionally significant events

• Auto-Extract Pipeline: Hooks into conversation flow to automatically extract and store new memories without explicit commands

• Auto-Surface: Context-aware passive recall — relevant memories are injected into conversations automatically

• Intelligent Deduplication: Embedding-based similarity detection (>80% threshold) with automatic merging

• MCP Protocol Native: Full integration with Claude Code and any MCP-compatible client

• Chunked Memory Support: Long memories are automatically chunked with parent-child relationships for granular retrieval

Related MCP server: Recall

Architecture

3-Agent Design (MAPLE v2)

┌──────────────────────────────────────────────────────────┐
│                    Claude Code / MCP Client               │
├──────────────────────────────────────────────────────────┤
│                      MCP Protocol                        │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │   Retrieval   │  │  Extraction  │  │  Maintenance │   │
│  │    Agent      │  │    Agent     │  │    Agent     │   │
│  │              │  │              │  │              │   │
│  │ • BM25       │  │ • Auto-      │  │ • Decay      │   │
│  │ • Semantic   │  │   extract    │  │ • Dedup      │   │
│  │ • Entity     │  │ • Auto-learn │  │ • Consolidate│   │
│  │ • Mood       │  │ • Surprise   │  │ • Expire     │   │
│  │ • Surface    │  │   scoring    │  │ • Rewrite    │   │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │
│         │                 │                 │            │
│  ┌──────▼─────────────────▼─────────────────▼────────┐   │
│  │              SQLite + Embeddings                   │   │
│  │  memories · chunks · FTS5 · cosine similarity     │   │
│  └───────────────────────────────────────────────────┘   │
├──────────────────────────────────────────────────────────┤
│  Auto-Surface Hook (UserPromptSubmit)                    │
│  Auto-Extract Hook (conversation flow → memory)          │
└──────────────────────────────────────────────────────────┘

The three agents operate independently:

• Retrieval Agent: Multi-channel search with weighted scoring (BM25 30% + Semantic 30% + Entity 20% + Mood 20%)

• Extraction Agent: Monitors conversations and automatically identifies memory-worthy content using surprise scoring

• Maintenance Agent: Background processes for decay, deduplication, consolidation, and expiration

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.

Key Technical Highlights

• Zero-config passive recall: Memories surface automatically via hooks — no explicit search commands needed in conversation

• Bilingual support: Chinese/English tokenization via jieba + transformer embeddings, supporting mixed-language memory retrieval

• Production-tested: Daily use across 30+ sessions with real conversation data

• Single-file deployment: SQLite-based, no external database required

• Extensible: MCP protocol means any compatible AI client can use this memory system

Status

In active daily use. Iterating based on real-world usage patterns. v3 with enhanced multi-agent coordination in progress.

License

MIT