Engraphy

Ассоциативная память для ИИ-агентов, смоделированная по образцу человеческого разума.

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

Engraphy — это самохостинговое решение. Она хранит то, что агент узнаёт, в виде типизированного графа знаний на Postgres + pgvector: записи дедуплицируются относительно существующей памяти, поиск объединяет семантический и лексический подходы, изоляция между пользователями обеспечивается базой данных, а вся форма памяти объявляется для каждого приложения как pack.

Она создана, чтобы заменить плоскую JSON-модель, однопользовательскую и stdio-ориентированную модель эталонного MCP-сервера памяти чем-то, что выдерживает конкурентность, перефразирование, дубликаты и годы накопленной памяти. Она говорит на Model Context Protocol, поэтому любой MCP-клиент (расширение VS Code, десктопное приложение, другой агент) может использовать её по HTTP.

Исходный код доступен. Лицензировано по Business Source License 1.1: читайте, запускайте, развивайте и используйте в продакшене для собственного продукта. Предложение самого Engraphy как хостинг- или управляемого сервиса третьим лицам зарезервировано за лицензиаром до даты изменения, когда лицензия преобразуется в Apache-2.0. См. Лицензию.

Что она делает

• Типизированный граф памяти. Воспоминания — это типизированные узлы (fact, decision, person, event, …), соединённые типизированными рёбрами (involves, references, supersedes, …). Типы, их схемы атрибутов и правила, какие рёбра могут соединять какие типы, объявляются для каждого пространства в pack и обеспечиваются в Postgres.

• Записи, которые дедуплицируются сами. Каждая запись встраивается и сравнивается с существующей памятью. Почти дословный пересказ автоматически объединяется; действительно новый, но связанный факт сохраняется как отдельный искомый узел и соединяется ребром (ничто не поглощается молча); пограничный случай помещается как ожидающий вердикт проверки на дубликат для разрешения вызывающей стороной. Каждая запись возвращает отчёт о резонансе — что она затронула.

• Гибридный поиск. search объединяет векторную часть (косинусное сходство по эмбеддингам) и лексическую часть (полнотекстовый поиск Postgres) с помощью Reciprocal Rank Fusion, а traverse проходит по рёбрам. Значения атрибутов включаются в поисковую поверхность, поэтому факт, хранящийся только в типизированном атрибуте, всё равно можно найти.

• Изоляция, обеспечиваемая базой данных. Несколько пространств и несколько субъектов внутри пространства разделяются с помощью Row-Level Security Postgres, работающей под ролью без прав суперпользователя, а не с помощью проверок приложения, которые можно забыть. Сервер подключается как роль NOBYPASSRLS.

• Маршрутизация областей, созданная для LLM. Каждая область несёт описание того, чем она управляет; доступный только для чтения инструмент scope_guide возвращает этот манифест маршрутизации, чтобы агент мог решить, куда должно попасть новое воспоминание, прежде чем записать его.

• Операторский CLI и поверхность MCP-инструментов для всего: от начальной настройки пространства до выпуска токенов, импорта данных, применения packs и проверки восстановлений.

Related MCP server: gbrain

Как это работает

flowchart LR
    C[MCP client<br/>VS Code · desktop · agent] -->|HTTP + bearer token| S[Engraphy server<br/>FastMCP]
    S --> E[Embedding<br/>nomic-embed-text-v1.5]
    S --> DB[(Postgres 16 + pgvector<br/>nodes · edges · scopes<br/>RLS · schema enforcement)]
    P[Pack<br/>types · edges · briefing] -.declares.-> DB

Запись встраивается, группируется по сходству в merge / merge-link / pending / new и фиксируется под идентификатором вызывающей стороны. Чтение (search, get, traverse, briefing) выполняется под RLS, поэтому вызывающая сторона видит только те области, которые ей предоставлены. Pack объявляет типы узлов, типы рёбер, схемы атрибутов и краткое описание на старте сессии для пространства, так что один движок обслуживает множество различных по форме приложений памяти. Обзор архитектуры подробно описывает полные пути записи и чтения.

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

Требования: Docker (с Compose). Облачный профиль поднимает Postgres, выполняет миграции, подготавливает роль приложения и запускает сервер одной командой.

# 1. Configure secrets (never committed)
cp deploy/.env.example .env   # then edit, or:
printf 'POSTGRES_PASSWORD=%s\nENGRAPHY_APP_ROLE_PASSWORD=%s\n' \
  "$(openssl rand -hex 16)" "$(openssl rand -hex 16)" > .env

# 2. Bring up Postgres + migrate + provision + serve
docker compose up -d          # first boot downloads the ~523 MB embedding model

# 3. Create a space, apply the starter pack, mint a client token
docker compose --profile admin run --rm admin \
  engraphy-admin space create --id personal --display-name "My Memory" --principal me
docker compose --profile admin run --rm admin \
  engraphy-admin pack apply packs/starter/pack.yaml --space personal
docker compose --profile admin run --rm admin \
  engraphy-admin token create --space personal --principal me \
    --client-name my-editor --role readwrite

Сервер теперь на 127.0.0.1:8000 (поставьте перед ним TLS-терминирующий обратный прокси, чтобы открыть доступ). Укажите любому MCP-клиенту на него с bearer-токеном. В руководстве по настройке описан также локальный путь без Docker.

Или позвольте скриптам сделать это

up.sh и provision.sh (с up.ps1 / provision.ps1 как эквивалентами для Windows) оборачивают ровно описанную выше последовательность и добавляют ожидание, которое не может обеспечить quickstart с копированием и вставкой:

./up.sh          # writes .env with random passwords, starts the stack,
                 # then blocks until /healthz returns 200
./provision.sh   # creates the space, applies the starter pack, mints a token,
                 # and prints the client settings to paste in

up.sh опрашивает /healthz, а не статус здоровья compose, потому что при первом запуске compose сообщает starting до тех пор, пока не заполнится кэш модели, что выглядит как цикл падения снаружи. Ответ 200 — это настоящий сигнал.

Оба скрипта безопасно перезапускать: существующий .env никогда не перезаписывается, а существующее пространство или уже применённый pack пропускается, а не считается ошибкой, поэтому повторный запуск всё равно выпускает свежий токен.

Всё параметризовано, с значениями по умолчанию, которые работают без изменений:

Токен печатается один раз и никогда не записывается на диск скриптами; сервер хранит только его SHA-256. Если вы его потеряете, перезапустите provision.sh для нового.

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

Engraphy — это MCP-сервер, поэтому клиент подключается и вызывает инструменты:

См. справочник инструментов для параметров, возвращаемых значений и примера для каждого инструмента. Расширение VS Code от первого лица находится в vscode-extension/.

Документация

• docs/: документация для разработчиков, архитектура, настройка, packs, справочник инструментов, развёртывание и сквозное руководство.

• design/: набор проектных документов, модель данных, поиск и дедупликация, аутентификация и аренда, операции, система pack/онтологии и тестовый стенд. Здесь находится инженерное обоснование.

• skills/: краткие рекомендации, которые LLM-агент может загрузить для эффективного использования Engraphy (запись и дедупликация, поиск, области и видимость, дисциплина ответов).

Требования

• Postgres 16 с pgvector (образ pgvector/pgvector:pg16 включает оба).

• Python ≥ 3.12.

• dbmate для миграций (входит в админ-контейнер; нужен только на PATH для пути без Docker).

• Модель эмбеддингов nomic-ai/nomic-embed-text-v1.5 (384-мерная, ~523 МБ, загружается и кэшируется при первом запуске).

Статус проекта

v0.1.0. Схема и ядро обеспечения, поведение движка (дедупликация, гибридный поиск, обход графа, брифинги), MCP-сервер с аутентификацией и администрированием, а также операторский CLI реализованы и покрыты тестовым набором с живым Postgres плюс CI-задачей, которая проверяет поставляемые артефакты развёртывания от начала до конца. Тестовый стенд (bench/, design/09) запускает движок на публичных наборах данных долговременной памяти; это инструмент для измерения изменений, а не источник маркетинговых цифр.

Лицензия

Engraphy лицензирована по Business Source License 1.1 (см. LICENSE).

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

• Вы не можете предлагать сам Engraphy третьим лицам как хостинг- или управляемый сервис до даты изменения.

• Дата изменения: 2026-08-22 + 4 года (2030-08-22), после чего лицензия преобразуется в Apache License, Version 2.0.

Copyright (c) 2026 Devon Clark.