EvolvMem

A fully-local, three-layer memory plugin for Claude Code with Chinese language support — FTS5/trigram + HNSW vector hybrid search.

Features

• L0 Active Memory: SessionStart injection — a project digest layer (recent per-project session summaries from :progress:log: memories, digest_* config), then pinned memories always injected, normal memories ranked by importance+recency+frequency score, the rest listed as a searchable index (progressive disclosure)

• L1 Full History: SQLite + FTS5/trigram exact search, supports Chinese substring matching

• L2 Semantic Index: USearch HNSW vector search for finding related memories expressed differently

• Self-Iteration: Auto-extraction, conflict detection, access-decay forgetting

• Consolidation: memory_consolidate finds and merges near-duplicate memories via vector similarity (dry-run by default)

• Semantic Merge: Write-time semantic merge — new values automatically supersede near-identical memories instead of duplicating them (add_merge_threshold) — plus weekly auto-consolidation at SessionStart (consolidate_auto_run_hours)

• Expiry: Memories can carry an expires_at date; expired memories stop being injected/searched and are archived automatically

• Project Relevance: SessionStart scoring boosts memories whose key matches the current project directory (configurable aliases)

• Quality Gate: memory_add/memory_replace reject values shorter than value_min_chars (default 10) and low-information placeholder phrases (e.g. "等待用户确认", "no action required"), keeping trivial auto-summary noise out of the store

Related MCP server: mcp-memory-graph

Quick Start

./install.sh

The script will automatically:

• Create ~/.claude/evolvmem/ directory and models/ subdirectory

• Install pip dependencies usearch and llama-cpp-python

• Download bge-small-zh-Q5_K_M.gguf (~50MB, skipped if already present)

• Generate default config.json

• Verify the Config module can be imported

Manual Configuration

Add the MCP Server config to ~/.claude/settings.json:

{
  "mcpServers": {
    "evolvmem": {
      "command": "python",
      "args": ["-m", "evolvmem.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/evolvmem-plugin"
      }
    }
  }
}

Optional: add a SessionStart hook for automatic active memory injection:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hook": "python -c \"from evolvmem.hooks import get_session_start_block; print(get_session_start_block())\"",
        "env": {
          "PYTHONPATH": "/path/to/evolvmem-plugin"
        }
      }
    ]
  }
}

Tools

Deletion is two-staged: memory_remove soft-deletes (recoverable via restore), while the Web Console's POST /api/memory/<id>/hard_delete permanently removes the row — irreversible, intended for confirmed junk. The quality gate above applies to every live memory_add/memory_replace call, so rejected values never enter the store in the first place.

Web Console

python -m evolvmem.web_server --host 0.0.0.0 --port 9377 serves a local console for browsing, filtering, editing and deleting memories (/api/stats, /api/memories, /api/memory/<id>/<action> with actions update|archive|restore|delete|hard_delete).

The stats "hot list" (top_accessed) ranks by composite heat — importance × (access_count + 1) — instead of raw hit count, so a high-importance memory with few hits outranks a trivial one that was matched often; each entry carries both access_count and importance so the two signals stay visible. Raw access_count still counts every retrieval hit and remains available as a pure frequency signal elsewhere in the console.

Data Directory

All data is stored under ~/.claude/evolvmem/:

Configuration

Edit ~/.claude/evolvmem/config.json to adjust the following parameters:

• fts_top_k / vector_top_k: FTS5 and vector search recall counts, default 20 each

• fts_weight / vector_weight: Hybrid search weight allocation, default 0.6 / 0.4

• forget_days_threshold: Days since last access before a memory can be archived, default 90

• forget_access_count_threshold: Max access count below which memories may be downgraded, default 2

• embedding_dim: Vector dimension, must match model, default 768

• embedding_query_prefix / embedding_doc_prefix: Task prefixes applied when embedding queries/documents (nomic defaults search_query: / search_document: , set to "" to disable)

• inject_max_count: Max memories injected on SessionStart, default 50

• inject_max_chars: Total character budget for SessionStart injection, default 8000

• inject_pinned_max_count / inject_pinned_max_chars: Max count and character budget for the pinned layer, default 10 / 2000

• inject_index_max_chars: Character budget for the index layer, default 1000 (0 disables the index layer)

• inject_key_prefix_quota: Max injected memories sharing the same key prefix (first two segments), default 3

• inject_w_importance / inject_w_recency / inject_w_frequency: Scoring weights for importance/10, recency decay, and log1p(access_count), default 0.5 / 0.3 / 0.2

• inject_recency_tau_days: Recency decay time constant in days, default 14.0

• inject_freq_norm_cap: Access-count normalization cap for frequency scoring, default 20

• inject_w_relevance: Weight of the project-relevance bonus in SessionStart scoring (memories whose key contains the current directory name — or its alias — as a substring), default 0.3

• inject_project_aliases: Map of directory name → memory key segment for project matching (e.g. {"my-project": "myproj"}), default {}

• consolidate_similarity_threshold: Similarity threshold above which two memories are near-duplicate merge candidates for memory_consolidate, default 0.92. Note the metric is similarity = (1+cos)/2 (not raw cosine): 0.92 corresponds to a true cosine of ≈ 0.84; for real merges a threshold ≥ 0.97 (≈ cosine 0.94) is recommended

• consolidate_auto_run_hours: Minimum interval between auto-consolidation runs at SessionStart (merges near-identical pairs at a conservative 0.97 threshold; failures never block session start), default 168 (weekly); 0 disables

• add_merge_threshold: Write-time semantic merge threshold — when a new value's similarity to an existing memory meets or exceeds it, the existing memory is superseded instead of adding a near-duplicate, default 0.95

• expires_at (per-memory field, not config): Optional expiry date set via memory_add (e.g. 2026-12-31); expired memories are excluded from injection and search, and are auto-archived

• forget_auto_run_hours: Minimum interval between auto-forgetting runs at SessionStart, default 24

• forget_rate_limit_days: Minimum interval between two downgrades of the same memory, default 7

• stop_hook_safe: Prevent Stop Hook infinite loops, default true

• value_max_chars: Hard length cap on memory_add/memory_replace values, default 500

• value_min_chars: Minimum length for memory_add/memory_replace values — shorter values are rejected as having no information content, default 10

Dependencies

Python dependencies (auto-installed by install.sh):

pip install usearch llama-cpp-python

Embedding model: BGE-small-zh Q5_K_M GGUF (~50MB), auto-downloaded by install.sh. For manual download, place bge-small-zh-Q5_K_M.gguf in ~/.claude/evolvmem/models/.

Architecture

Three-layer memory structure: active memory (L0, SessionStart system prompt injection) -> exact retrieval (L1, SQLite + FTS5/trigram) -> semantic retrieval (L2, USearch HNSW). Memories self-iterate through auto-extraction, conflict detection, and access-decay forgetting. All data is stored locally, no external services required.