Graph Memory

Локальная память на основе графа знаний для ИИ-агентов кодирования — один межпроектный граф, который может запрашивать любой диалог, чтобы агент в одной сессии получал знания, накопленные во всех остальных.

Локальная система памяти на основе графа знаний, заменяющая традиционное разделение памяти агента по сессиям. Использует граф знаний + диффузионный поиск PageRank для установления связей между концепциями, позволяя агенту в одной сессии получать доступ к знаниям всех проектов.

Краткое описание на английском: Graph Memory заменяет память по сессиям единым локальным графом знаний. Поиск начинается с семантических ближайших соседей и распространяется через персонализированный PageRank по автоматически построенным рёбрам, объединяя 50% семантических + 50% графовых диффузионных оценок. Предоставляет агентам 5 инструментов через MCP и включает визуализацию на Cytoscape.js. Всё работает локально — эмбеддинги создаются локальной моделью sentence-transformers, граф хранится в JSON-файле, а LLM используется (опционально) только для извлечения знаний.

Возможности / Features

• Ассоциативный поиск по графу — PageRank распространяется по рёбрам графа, выводя из одной технической точки связанные детали развёртывания, извлечённые уроки или предпочтения пользователя

• Извлечение знаний через LLM — автоматическое извлечение структурированных узлов знаний из диалогов/памяти

• Трёхуровневая дедупликация — MD5 → сходство эмбеддингов >0,85 → создание нового

• Коррекция памяти — при обнаружении устаревшей информации можно обновить существующие узлы

• Интеграция MCP — автоматическое предоставление 5 инструментов каждому агенту через MCP

• Визуализация — тёмная тема Cytoscape.js, фильтрация/добавление/удаление/изменение

• Локальный запуск — данные не покидают устройство, модель эмбеддингов загружается локально

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

1. Установка

git clone https://github.com/yourname/graph-memory.git
cd graph-memory
pip install -e ".[mcp,dotenv]"

2. Конфигурация

cp .env.example .env
# 编辑 .env 填入 LLM API key 和 base_url(检索/写入不需要 LLM,只有 extract 需要)

3. Запуск

python -m graph_memory.server

Откройте http://127.0.0.1:9121/ для просмотра интерфейса визуализации.

При первом запуске будет загружена модель эмбеддингов (по умолчанию BAAI/bge-base-zh-v1.5, около 400 МБ), после чего она будет кэшироваться локально.

3a. Демонстрационные данные (необязательно)

При первом использовании можно сразу загрузить набор общих технических примеров, чтобы пустой проект работал из коробки:

python seed_demo.py

Затем на http://127.0.0.1:9121/ можно увидеть небольшой граф. Очистка демонстрационных данных: удалите data/graph.json и data/embeddings.npz, затем перезапустите сервер.

3b. Docker запуск одной командой

docker build -t graph-memory .
docker run -p 9121:9121 -v gm_data:/app/data -v gm_models:/root/.cache/huggingface graph-memory

4. Импорт существующей памяти

При первом использовании импортируйте существующую память из Hermes / Claude Code / Codex:

curl -X POST http://127.0.0.1:9121/api/import?source=all

Также можно пакетно извлечь историю сессий Claude Code:

curl -X POST http://127.0.0.1:9121/api/extract/sessions

Пути импорта можно переопределить через переменные окружения (HERMES_HOME / CLAUDE_HOME / CODEX_HOME), по умолчанию они указывают на стандартные расположения агентов в домашнем каталоге пользователя.

Использование в агенте

MCP Server (доступен автоматически)

Добавьте MCP-сервер graph-memory в конфигурацию MCP вашего агента, после перезапуска автоматически будут доступны 5 инструментов:

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

MCP-сервер работает через stdio и выступает в роли HTTP-клиента к FastAPI-серверу, сам не загружает модель, чтобы не иметь две несогласованные копии графа данных.

Skill (инструкция для агента)

SKILL.md — это инструкция по использованию для агента. После загрузки агент будет следовать правилам:

• Перед ответом сначала выполнять поиск по графу памяти

• После ответа извлекать ценные новые знания и записывать их

• Если обнаружена устаревшая информация, активно обновлять

Способы использования

Способ 1: Прямой диалог с агентом

"Помоги мне посмотреть проект по инференсу на сервере"

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

Способ 2: Попросить агента запомнить новые знания

"Запомни, что vLLM 0.25 добавил поддержку speculative decoding"

Агент вызовет write для записи знаний в граф, автоматически связывая с существующими узлами.

Способ 3: Исправление устаревшей информации

"Порт сервиса уже изменён, не 8000"

Агент вызовет update для обновления существующего узла.

Способ 4: Визуальный просмотр

Откройте http://127.0.0.1:9121/ для поиска, фильтрации, добавления/удаления/изменения.

Архитектура

┌──────────────────────────────────────────┐
│  Agent (Hermes / Claude Code / ...)       │
│  ┌─────────────┐  ┌──────────────────┐   │
│  │ MCP Client  │  │ Skill (指导)     │   │
│  └──────┬──────┘  └──────────────────┘   │
│         │ stdio                           │
│  ┌──────▼──────┐                          │
│  │ MCP Server  │  (轻量, 不加载模型)       │
│  │ mcp_server  │                          │
│  └──────┬──────┘                          │
└─────────┼─────────────────────────────────┘
          │ HTTP
┌─────────▼─────────────────────────────────┐
│  FastAPI Server (port 9121)              │
│  ┌───────────┐  ┌──────────┐  ┌────────┐ │
│  │ GraphEngine│  │ LLM提取  │  │ 导入器 │ │
│  │ NetworkX  │  │ OpenAI   │  │        │ │
│  │ PageRank  │  │ 兼容API  │  └────────┘ │
│  │ bge embed │  └──────────┘              │
│  └───────────┘                            │
│       │                                   │
│  ┌────▼────┐  ┌────────────┐              │
│  │ graph   │  │ embeddings │              │
│  │ .json   │  │ .npz       │              │
│  └─────────┘  └────────────┘              │
└─────────────────────────────────────────────┘

MCP-сервер — это лёгкий HTTP-клиент, не загружающий модель эмбеддингов. Все вычисления выполняются на FastAPI-сервере, чтобы избежать несогласованности данных из-за двух процессов, каждый из которых держит свой движок.

API

Бенчмарк

python benchmark.py

30 вопросов × 3 раунда × оценка LLM, сравнение качества ответов "только MEMORY.md" против "с графом памяти".

Набор вопросов нужно настраивать под вашу собственную базу знаний (см. комментарии в начале benchmark.py). Регрессионное тестирование поведения поиска выполняется с помощью regression.py (детерминированное сравнение снимков, не зависит от LLM):

python regression.py snapshot baseline      # 改代码前
python regression.py snapshot after-change  # 改代码后
python regression.py compare baseline after-change

Тестирование

pip install -e ".[test]"
pytest tests/ -q

Тесты движка используют детерминированный фейковый эмбеддер, не загружают реальную модель, поэтому работают офлайн.

Управление знаниями (защита от разрастания)

При длительном использовании граф будет расширяться. Регулярно запускайте инструменты управления:

python manage.py status        # 查看图健康状态
python manage.py dedup         # 扫描重复节点报告
python manage.py merge          # 合并相似节点(embedding >0.85)
python manage.py prune --dry-run   # 预览孤立+过时节点
python manage.py prune              # 执行清理

Правила очистки:

• Узлы со степенью <2 и не обновлявшиеся 90 дней удаляются (связанные сохраняются)

• При объединении похожих узлов сохраняется более длинное/подробное содержимое

• Все операции поддерживают предварительный просмотр с --dry-run

Параметры конфигурации

Лицензия

MIT