Engram

Every thought leaves a trace.

Equip your AI Agent with a brain that knows how to forget.

Engram is a fully local MCP memory service. It doesn't just "store and retrieve"—it simulates human memory mechanisms like forgetting, reinforcement, and association, allowing Agents to remember what truly matters across sessions while naturally letting go of unnecessary details.

Zero cloud dependency; your data stays on your machine forever.

Pain Points Solved

Pain Point 1: Broken Cross-Session State

Every AI Agent conversation starts with a blank slate. The preferences you shared yesterday, the architectural decisions made last week, the pitfalls encountered last month—all reset in the next conversation. Clearing the context window is like formatting the brain.

Pain Point 2: File Entropy

Stuffing context into CLAUDE.md or .cursorrules seems to solve the problem but actually creates new ones: files grow indefinitely, outdated information mixes with new, and manual maintenance costs keep rising. You aren't managing memory; you're maintaining an increasingly unreadable document.

Pain Point 3: Lost Engineering State

What the Agent did, where it got stuck, what the next step should be—there's no place to store this structured engineering state. Every new session requires 10 minutes of "re-alignment" before repeating the same work.

Engram's Solution: Instead of "saving everything," it simulates the human forgetting-reinforcement-association mechanism:

• Important preferences and decisions decay extremely slowly, remaining almost permanently.

• Temporary debugging context naturally fades away after 11 days.

• Knowledge that is recalled repeatedly becomes stronger with each use.

• Contradictory information is automatically overwritten, preventing internal conflicts.

• v0.2 New: Structured session handoff, allowing the next session to continue from a breakpoint rather than from scratch.

• v0.4 New: Engineering State Hub — structured failure attribution (track_failure) and progress tracking (track_progress), enabling the Agent to remember not just information, but engineering state.

Related MCP server: alaya

Core Mechanisms

1. Ebbinghaus Forgetting Curve

Every memory has a strength value that decays over time following an exponential curve:

effective_λ = base_λ × (1 - importance × 0.8)
strength = importance × e^(-λ × days) × (1 + recall_count × 0.2)

Three factors determine how long a memory lasts:

Four Memory Categories:

Design Intent: Successful strategies are remembered longest (strategy ~38 days), while lessons from failures are remembered shortest (failure ~11 days)—because environments change, and yesterday's pitfall might be fixed by tomorrow.

2. Intelligent Deduplication and Conflict Resolution

When storing new memories, the system doesn't just append; it performs semantic comparison with existing memories first:

相似度 ≥ 0.85 → REINFORCE  只增加回忆次数，不重复存储
相似度 0.65~0.84 → 检测矛盾
  ├── 语义矛盾 → REPLACE   用新内容覆盖旧内容
  └── 语义兼容 → MERGE     合并为一条更完整的记忆
相似度 < 0.65 → NEW        存为新记忆

Conflict detection is achieved through polarity analysis: extracting positive words (prefer/love/adopt) and negative words (avoid/hate/reject), combined with negation (not/don't/never), to determine if two memories express opposing stances.

Example: If "User prefers TypeScript" exists, and "User decides to abandon TypeScript for Go" is stored, the system identifies a conflict and automatically replaces the old memory with the new one.

3. Hybrid Retrieval (Vector + BM25 + Graph)

Retrieval uses a three-way hybrid scoring system:

最终得分 = 0.4 × BM25关键词得分 + 0.6 × (语义相似度 × 衰减强度) + 图谱加成

Why not just use vector search?

Three-way fusion effect: Querying "database performance" not only finds memories that explicitly mention performance but also uses the graph to find related indexing strategies, caching decisions, etc.

4. Semantic Graph

Every memory automatically establishes semantic associations with existing memories upon storage:

• Calculate cosine similarity with all existing memories

• Establish bidirectional edges for similarity ≥ 0.40, with weight = similarity × 0.5

• Each memory connects to at most 5 most similar neighbors

Two Key Roles of the Graph:

Associative Discovery: During retrieval, start from the hit memory and perform BFS (max depth 2) along edges to find associated memories, even if they lack direct semantic similarity to the query. It mimics human "associative thinking."

Chain Protection: When a memory's own strength falls below the threshold, if its neighbors still contain strong memories, it is preserved—as it may be the bridge connecting two important pieces of knowledge.

5. Automatic Consolidation and Pruning

Background maintenance tasks run every 12 hours:

Consolidation:

1. Identify memory clusters with similarity ≥ 0.70

2. Keep the one with the highest importance as the primary memory

3. Merge unique information from other memories

4. Recalculate vectors and graph relationships

5. Delete redundant merged memories

Pruning:

1. Calculate current strength for each memory

2. Strength < 0.05 and passes chain safety check → Delete

3. Strength < 0.05 but neighbors are still strong → Preserve (Chain Protection)

This means the memory bank stays lean automatically—no manual cleanup required, and it won't expand infinitely.

Engineering State Hub (v0.4)

Engram is not just a memory plugin for "storing info"—it is a state layer that understands engineering workflows.

Failure Attribution (track_failure)

When an Agent encounters bugs, test failures, or deployment issues, record them in a structured format:

# MCP 调用
track_failure(
    error="CSRF token missing on checkout",
    component="payment",
    severity="critical",        # → importance=0.9
    root_cause="middleware not loaded after refactor",
    fix="re-add CsrfMiddleware to pipeline",
    related_test_ids=["test_checkout_01", "test_payment_csrf"]
)

Design Decisions:

• severity automatically maps to importance (critical=0.9, major=0.7, minor=0.5)

• Fixed failure category (fastest decay λ=0.35, ~11-day half-life)—environments change, old failure records naturally expire

• component field supports aggregated statistics by module, quickly locating high-risk areas

Progress Tracking (track_progress)

Track feature/task status across sessions:

track_progress(
    feature="login-flow-refactor",
    status="in_progress",       # → importance=0.8
    completion=60,
    blockers=["waiting for API design review"],
    quality_score=0.85,
    notes="auth module done, UI pending"
)

Design Decisions:

• status automatically maps to importance (blocked=0.9 highest, done=0.5 lowest)

• Fixed strategy category (slowest decay λ=0.10, ~38-day half-life)—progress status should be remembered longest

• Completed features naturally decay and disappear, no manual cleanup needed

Engineering Metrics (memory_stats enhancement)

memory_stats now automatically aggregates engineering data:

{
  "total": 42,
  "categories": {"fact": 20, "failure": 8, "strategy": 14},
  "engineering": {
    "failures": {
      "total": 8,
      "by_component": {"auth": 5, "payment": 3},
      "by_severity": {"critical": 2, "major": 6}
    },
    "features": {
      "total_tracked": 4,
      "active": {
        "login-refactor": {"status": "in_progress", "completion": 60},
        "payment-fix": {"status": "blocked", "completion": 30}
      }
    }
  }
}

Technical Architecture

┌──────────────────────────────────────────────┐
│              MCP Client                      │
│      (Claude Code / Cursor / ...)            │
└──────────────────┬───────────────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼───────────────────────────┐
│              server.py                       │
│  8 MCP tools  ·  APScheduler (12h 维护)      │
├──────────────────────────────────────────────┤
│                                              │
│  ┌─ 写入路径 ──────┐  ┌─ 读取路径 ──────┐    │
│  │  resolve.py     │  │  retrieve.py    │    │
│  │  去重/矛盾消解   │  │  混合检索+评分   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
│  ┌─ 维护路径 ──────┐  ┌─ 统计路径 ──────┐    │
│  │  consolidator   │  │  decay.py       │    │
│  │  聚类合并+剪枝   │  │  遗忘曲线+强度   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
├──────────────────────────────────────────────┤
│  embedding.py          │  graph.py           │
│  768d / 1024d 向量编码  │  NetworkX 语义图谱  │
├──────────────────────────────────────────────┤
│              db.py — DuckDB                  │
│  向量存储  ·  BM25 全文索引  ·  CRUD          │
└──────────────────────────────────────────────┘

数据文件（~/.engram/）：
├── memories.duckdb     # 向量数据库（单文件，零运维）
├── graph.json          # 语义图谱（JSON 序列化）
└── model_cache/        # 嵌入模型缓存

MCP Tool Interface

Importance Reference

Benefits to Users

1. The Agent Truly "Knows" You

No need to re-introduce your tech stack, coding habits, and project background every conversation. The Agent remembers you prefer Go over Java, knows your project uses a monorepo, and understands the architectural decisions you made last week.

2. Knowledge Naturally Evolves

Conflict resolution means the Agent's cognition is always up-to-date. Switching from React to Vue? One conversation automatically updates it. No need to manually maintain a list of "what the Agent should know."

3. Zero Maintenance

• No manual cleanup of old memories—forgetting curves prune them automatically

• No manual merging of duplicates—the consolidator handles it

• No worries about data bloat—automatic maintenance every 12 hours

• No external services—DuckDB single-file, ready to use out of the box

4. Complete Privacy

All data is stored in ~/.engram/, no networking, no uploading, no reliance on any cloud service. Embedding models run locally. Your memory is yours.

5. Associative Discovery

Graph expansion allows the Agent to not just "search and return," but to follow semantic associations to find relevant knowledge that doesn't directly match. It's like asking an old colleague a question; they don't just answer the question, they add, "By the way, this is related to that thing from last time."

6. Smarter with Use

Recall reinforcement mechanism: memories recalled repeatedly gain higher strength and decay slower. The Agent automatically learns what knowledge is most valuable to you.

Quick Start

# 安装
pip install mcp-engram

# 初始化（下载模型、创建数据库）
engram-setup

# 按照输出提示将配置块添加到 Claude Code 配置中

Claude Code Configuration

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": {
        "HF_ENDPOINT": "https://hf-mirror.com"
      }
    }
  }
}

CLAUDE.md Integration

Add to your project's CLAUDE.md:

## Memory Rules

### Step 1 — 先回忆再行动
每次任务开始时，用请求中的关键词调用 `recall_memory`。

### Step 2 — 学到新东西就存
| 情况 | 操作 |
|------|------|
| 全新知识 | `store_memory(content, importance)` |
| 补充已有 | `update_memory(memory_id, merged_content)` |
| 推翻已有 | `update_memory(memory_id, new_content)` |

Environment Variables

Key Threshold Quick Reference

LoCoMo Benchmark Evaluation

Retrieval quality evaluation based on LoCoMo (Snap Research long-term conversation memory benchmark). LoCoMo is the standard evaluation used by products like Mem0/Zep/Memobase/MemMachine.

Evaluation Configuration

• Dataset: locomo10.json (2/10 conversations, 233 QA, excluding adversarial)

• Retrieval: recall() top-k=5

• LLM: DeepSeek-V3.2 / GLM-5.1 (Note: baseline products use GPT-4o-mini)

• Metrics: Token-level F1 (official LoCoMo metric) + Hit@5 (LLM-independent retrieval hit rate)

Turn Mode — Best Configuration (bge-m3 + bge-reranker-v2-m3, DeepSeek-V3.2)

Two-stage retrieval: recall top-50 → CrossEncoder rerank to top-5, importance=1.0 correction weight ratio

Turn Mode — Optimization Path (DeepSeek-V3.2)

Four rounds of optimization cumulative F1 +50.3% (0.29 → 0.44), Hit@5 +26.2pp (51.5% → 77.7%).

Turn Mode — LLM Comparison (all-mpnet-base-v2)

Observation Mode (abstract assertive facts)

Comparison with Industry Baselines

Conclusion: Four rounds of optimization mpnet(0.29) → bge-m3(0.35) → +reranker(0.39) → +weight fix+r50(0.44). Hit@5: 51.5% → 77.7%. The gap with Mem0(0.67) narrowed from 56% to 35%.

Best Config Quick Reference

Recommended Config: bge-m3 (1024d) + bge-reranker-v2-m3 two-stage retrieval

Metric	Value	Description
Overall F1	0.4383	Token-level, DeepSeek-V3.2
Overall Hit@5	77.7%	Pure retrieval hit rate, LLM-independent
Temporal Hit@5	95.2%	Outstanding performance on temporal questions
Optimization Magnitude	F1 +50.3%, Hit +26.2pp	Four rounds cumulative (relative to initial mpnet)

Key parameters: recall top-50 → rerank to top-5, importance=1.0 correction weight ratio. Local deployment with zero cloud dependency, gap with Mem0 (using GPT-4o-mini) narrowed to 35%.

Development

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v

License

MIT