memory-mcp: Instructions file for Claude Code

Memory MCP - Project Instructions

Core Value Proposition

The Engram Insight: Frequently-used patterns should be instantly available, not searched for.

This project differentiates from generic memory servers (like mcp-memory-service) through:

1. Two-Tier Memory Architecture

   • Hot Cache: Session-aware context printed into Claude's context at 0ms by the SessionStart and UserPromptSubmit hooks (no tool call needed)
   • Cold Storage: Semantic search for everything else

2. Salience-Based Promotion

   • Unified salience score: importance + trust + access count + recency
   • Auto-promote when salience ≥ 0.5 AND access count ≥ 3
   • Auto-demote after 14 days without access
   • Pin important memories to prevent auto-eviction

3. Hot Cache Resource

   • memory://hot-cache: Session-aware active context (~10 items)
   • Combines: recently recalled, predicted next, top promoted items
   • Backed by promoted memories (~20 items)

4. Multi-Hop Recall

   • expand_relations=true traverses knowledge graph
   • Finds associated memories via typed relationships
   • Score decay prevents dilution of results

5. Episodic Memory

   • Session-bound short-term context (7-day retention)
   • end_session() promotes top memories to long-term storage
   • Consolidates session context automatically

6. Knowledge Graph

   • Link related memories with typed relationships
   • Relation types: relates_to, depends_on, contradicts, supersedes, refines, elaborates

7. Trust Management

   • Strengthen/weaken memory confidence with contextual reasons
   • Per-memory-type trust decay rates
   • Audit trail for trust changes

8. Memory Consolidation

   • consolidate CLI merges semantically similar memories
   • Reduces redundancy while preserving information

Architecture

flowchart LR
    subgraph LLM["Claude"]
        REQ((Request))
    end

    subgraph Hot["Hot Tier · 0ms"]
        HC[memory://hot-cache]
        PM[(Promoted memories)]
    end

    subgraph Cold["Cold Tier · ~50ms"]
        VS[(Vector Store)]
        KG[(Knowledge Graph)]
    end

    REQ -->|"hook stdout"| HC
    HC -.->|"draws from"| PM
    REQ -->|"recall()"| VS
    VS <-->|"expand_relations"| KG