Engram

Каждая мысль оставляет след.

Установите AI-агенту мозг, который умеет забывать.

Engram — это полностью локальный сервис памяти MCP. Это не просто «хранилище» — он имитирует человеческие механизмы забывания, подкрепления и ассоциаций, позволяя агенту запоминать действительно важные вещи между сессиями и естественным образом отбрасывать ненужные детали.

Нулевая зависимость от облака, данные всегда остаются на вашем устройстве.

Какие проблемы это решает

Проблема 1: Разрыв состояния между сессиями

Каждый диалог с AI-агентом — это чистый лист. Предпочтения, о которых вы рассказали вчера, архитектурные решения, принятые на прошлой неделе, или ошибки, на которых вы учились в прошлом месяце — всё это обнуляется при следующем диалоге. Очистка контекстного окна = форматирование мозга.

Проблема 2: Энтропия файлов

Запихивание контекста в CLAUDE.md / .cursorrules кажется решением, но на деле создает новые проблемы: файлы становятся бесконечно длинными, устаревшая информация смешивается с актуальной, а затраты на ручное обслуживание постоянно растут. Вы не управляете памятью, вы поддерживаете документ, который становится всё труднее читать.

Проблема 3: Потеря инженерного состояния

Что сделал агент, на чем он застрял, что нужно сделать дальше — для этих структурированных инженерных состояний нет места для хранения. Каждая новая сессия требует 10 минут на «повторную синхронизацию», после чего приходится делать одно и то же.

Решение Engram: Не «сохранять всё подряд», а имитировать человеческий механизм забывания-подкрепления-ассоциаций:

• Важные предпочтения и решения затухают крайне медленно, сохраняясь почти навсегда.

• Временный контекст отладки естественным образом исчезает через 11 дней.

• Знания, к которым часто обращаются, становятся прочнее.

• Противоречивая информация автоматически перезаписывается, предотвращая конфликты.

• Новое в v0.2: Структурированная передача сессии (session handoff), позволяющая следующей сессии продолжаться с точки остановки, а не с нуля.

• Новое в v0.4: Центр инженерного состояния — структурированное определение причин сбоев (track_failure) и отслеживание прогресса (track_progress), позволяющее агенту запоминать не только информацию, но и инженерный статус.

Related MCP server: Ori Mnemos

Основные механизмы

1. Кривая забывания Эббингауза

Каждое воспоминание имеет значение силы (strength), которое экспоненциально затухает со временем:

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

Три фактора определяют, как долго «проживет» воспоминание:

Четыре категории памяти:

Дизайн-идея: Успешные стратегии запоминаются дольше всего (strategy ~38 дней), а уроки неудач — короче всего (failure ~11 дней), так как окружение меняется, и вчерашняя проблема завтра может быть уже решена.

2. Интеллектуальное устранение дубликатов и разрешение противоречий

При сохранении нового воспоминания система не просто добавляет его, а сначала проводит семантическое сравнение с уже существующими:

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

Детекция противоречий реализуется через анализ полярности: извлечение позитивных слов (prefer/love/adopt) и негативных слов (avoid/hate/reject) вместе с отрицаниями (not/don't/never) для определения того, выражают ли два воспоминания противоположные позиции.

Пример: если уже есть «предпочтение TypeScript», а сохраняется «пользователь решил отказаться от TypeScript в пользу Go», система распознает противоречие и автоматически заменит старое воспоминание новым.

3. Гибридный поиск (векторный + BM25 + граф)

При извлечении воспоминаний используется трехкомпонентная гибридная оценка:

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

Почему не использовать только векторный поиск?

Эффект объединения: при поиске по запросу «производительность базы данных» можно найти не только воспоминания, прямо упоминающие производительность, но и через граф найти связанные стратегии индексации, решения по кэшированию и т.д.

4. Семантический граф

Каждое воспоминание при сохранении автоматически устанавливает семантические связи с уже существующими:

• Вычисляется косинусное сходство со всеми существующими воспоминаниями.

• При сходстве ≥ 0.40 создается двунаправленное ребро с весом = сходство × 0.5.

• Каждое воспоминание соединяется максимум с 5 наиболее похожими соседями.

Две ключевые функции графа:

Ассоциативное обнаружение: при поиске выполняется BFS (макс. глубина 2) от найденных воспоминаний, чтобы найти связанные, даже если они не имеют прямого семантического сходства с поисковым запросом. Это похоже на человеческую ассоциацию «от одного к другому».

Цепная защита: если сила самого воспоминания падает ниже порога, но среди его соседей есть сильные воспоминания, оно сохраняется — так как может быть мостом между двумя важными знаниями.

5. Автоматическая консолидация и удаление

Фоновая задача обслуживания запускается каждые 12 часов:

Консолидация (Consolidation):

1. Поиск кластеров воспоминаний со сходством ≥ 0.70.

2. Сохранение наиболее важного воспоминания как основного.

3. Объединение уникальной информации из остальных.

4. Пересчет векторов и графовых связей.

5. Удаление избыточных воспоминаний.

Удаление (Pruning):

1. Расчет текущей силы каждого воспоминания.

2. Сила < 0.05 и прохождение проверки цепной защиты → удаление.

3. Сила < 0.05, но соседи сильны → сохранение (цепная защита).

Это означает, что база памяти автоматически остается компактной — не нужно ручной очистки, и она не будет бесконечно раздуваться.

Центр инженерного состояния (v0.4)

Engram — это не просто плагин памяти для «хранения информации», это слой состояния, понимающий инженерные процессы.

Определение причин сбоев (track_failure)

Когда агент сталкивается с багом, неудачным тестом или проблемой развертывания, это записывается в структурированном формате:

# 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"]
)

Дизайн-решения:

• severity автоматически отображается на importance (critical=0.9, major=0.7, minor=0.5).

• Фиксированная категория failure (самое быстрое затухание λ=0.35, период полураспада ~11 дней) — окружение меняется, старые записи об ошибках естественным образом устаревают.

• Поле component поддерживает агрегированную статистику по модулям для быстрого поиска зон высокого риска.

Отслеживание прогресса (track_progress)

Отслеживание состояния функций/задач между сессиями:

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"
)

Дизайн-решения:

• status автоматически отображается на importance (blocked=0.9 самый высокий, done=0.5 самый низкий).

• Фиксированная категория strategy (самое медленное затухание λ=0.10, период полураспада ~38 дней) — статус прогресса нужно помнить дольше всего.

• Завершенные функции естественным образом затухают и исчезают, ручная очистка не требуется.

Инженерные метрики (улучшенный memory_stats)

memory_stats теперь автоматически агрегирует инженерные данные:

{
  "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}
      }
    }
  }
}

Техническая архитектура

┌──────────────────────────────────────────────┐
│              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

Справочник важности

Преимущества для пользователя

1. Агент по-настоящему «знает» вас

Больше не нужно каждый раз представлять свой стек технологий, привычки кодинга и контекст проекта. Агент помнит, что вы предпочитаете Go, а не Java, знает, что у вас monorepo, и понимает архитектурные решения, принятые на прошлой неделе.

2. Естественная эволюция знаний

Разрешение противоречий означает, что знания агента всегда актуальны. Перешли с React на Vue? Один диалог автоматически обновит данные. Не нужно вручную поддерживать список того, «что агент должен знать».

3. Нулевое обслуживание

• Не нужно вручную чистить старую память — кривая забывания делает это автоматически.

• Не нужно вручную объединять дубликаты — консолидатор делает это сам.

• Не нужно беспокоиться о раздувании данных — автоматическое обслуживание каждые 12 часов.

• Не нужны внешние сервисы — DuckDB в одном файле, работает «из коробки».

4. Полная конфиденциальность

Все данные хранятся в ~/.engram/, нет выхода в сеть, нет загрузки в облако, нет зависимости от сторонних сервисов. Модели эмбеддингов также работают локально. Ваша память принадлежит только вам.

5. Ассоциативное обнаружение

Графовое расширение позволяет агенту не просто «найти то, что искали», но и пройти по семантическим связям, чтобы найти связанные, но не прямо совпадающие знания. Это как спросить коллегу о чем-то: он не только ответит на вопрос, но и добавит: «Кстати, это связано с тем случаем на прошлой неделе».

6. Становится умнее с использованием

Механизм подкрепления воспоминаний: воспоминания, к которым часто обращаются, становятся сильнее, а затухают медленнее. Агент автоматически учится тому, какие знания для вас наиболее ценны.

Быстрый старт

# 安装
pip install mcp-engram

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

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

Настройка Claude Code

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

Интеграция CLAUDE.md

Добавьте в 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)` |

Переменные окружения

Справочник пороговых значений

Бенчмарк LoCoMo

Оценка качества поиска на основе LoCoMo (стандарт для долгосрочной памяти в диалогах от Snap Research). LoCoMo — это стандарт, используемый такими продуктами, как Mem0/Zep/Memobase/MemMachine.

Конфигурация оценки

• Датасет: locomo10.json (2/10 диалогов, 233 QA, исключая adversarial)

• Поиск: recall() top-k=5

• LLM: DeepSeek-V3.2 / GLM-5.1 (Примечание: базовые продукты используют GPT-4o-mini)

• Метрики: Token-level F1 (официальная метрика LoCoMo) + Hit@5 (точность попадания без участия LLM)

Turn Mode — Лучшая конфигурация (bge-m3 + bge-reranker-v2-m3, DeepSeek-V3.2)

Двухэтапный поиск: recall top-50 → CrossEncoder rerank to top-5, корректировка веса importance=1.0

Turn Mode — Путь оптимизации (DeepSeek-V3.2)

Четыре этапа оптимизации дали суммарный прирост F1 +50.3% (0.29 → 0.44), Hit@5 +26.2pp (51.5% → 77.7%).

Turn Mode — Сравнение LLM (all-mpnet-base-v2)

Observation Mode (абстрактные утвердительные факты)

Сравнение с отраслевыми стандартами

Вывод: Четыре этапа оптимизации mpnet(0.29) → bge-m3(0.35) → +reranker(0.39) → +weight fix+r50(0.44). Hit@5: 51.5% → 77.7%. Разрыв с Mem0(0.67) сократился с 56% до 35%.

Справочник Best Config

Рекомендуемая конфигурация: bge-m3 (1024d) + bge-reranker-v2-m3 двухэтапный поиск

Метрика	Значение	Описание
Overall F1	0.4383	Token-level, DeepSeek-V3.2
Overall Hit@5	77.7%	Чистая точность поиска, LLM-независимая
Temporal Hit@5	95.2%	Отличные показатели в вопросах по времени
Масштаб оптимизации	F1 +50.3%, Hit +26.2pp	Суммарно за 4 этапа (относительно начального mpnet)

Ключевые параметры: recall top-50 → rerank to top-5, importance=1.0 корректировка веса. Локальное развертывание без облачных зависимостей, разрыв с Mem0 (использующим GPT-4o-mini) сокращен до 35%.

Разработка

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

Лицензия

MIT