Engraphy

AI 에이전트를 위한 자체 호스팅 메모리 엔진. Engraphy는 에이전트가 학습한 내용을 Postgres + pgvector 기반의 타입화된 지식 그래프로 저장합니다. 쓰기는 기존 메모리에 대해 자동으로 중복 제거되고, 검색은 의미론적(semantic) 검색과 어휘적(lexical) 검색을 융합하며, 사용자 간 격리는 데이터베이스가 강제하고, 메모리의 전체 구조는 애플리케이션별로 팩(pack) 으로 선언됩니다.

이 프로젝트는 참조 MCP 메모리 서버의 평면 JSON, 단일 사용자, stdio 모델을 대체하여 동시성, 의역, 중복, 그리고 수년간 축적된 메모리를 견디는 무언가를 제공하기 위해 존재합니다. Model Context Protocol을 사용하므로 모든 MCP 클라이언트(VS Code 확장, 데스크톱 앱, 다른 에이전트)가 HTTP를 통해 사용할 수 있습니다.

소스 공개(Source-available). Business Source License 1.1에 따라 라이선스가 부여됩니다: 읽고, 실행하고, 이를 기반으로 구축하고, 자체 제품의 프로덕션 환경에서 사용할 수 있습니다. Engraphy 자체를 제3자에게 호스팅 또는 관리형 서비스로 제공하는 것은 Change Date까지 라이선스 제공자(Licensor)에게 유보되며, 이후 Apache-2.0으로 전환됩니다. 라이선스를 참조하세요.

제공 기능

• 타입화된 메모리 그래프. 메모리는 타입화된 노드(fact, decision, person, event, …)로 저장되며 타입화된 엣지(involves, references, supersedes, …)로 연결됩니다. 타입, 속성 스키마, 그리고 어떤 엣지가 어떤 타입을 연결할 수 있는지에 대한 규칙은 스페이스별로 팩에 선언되고 Postgres에서 강제됩니다.

• 자동 중복 제거되는 쓰기. 모든 쓰기는 임베딩되어 기존 메모리와 대역(band) 비교됩니다. 거의 그대로 반복된 진술은 자동 병합되고, 진정으로 새롭지만 관련된 사실은 자체 검색 가능한 노드로 유지되며 엣지로 연결됩니다(조용히 흡수되지 않음). 경계선에 걸친 경우는 보류 중인 중복 확인 판정으로 대기시켜 호출자가 해결하도록 합니다. 모든 쓰기는 무엇에 영향을 주었는지에 대한 공명 보고서(resonance report) 를 반환합니다.

• 하이브리드 검색. search는 벡터 레그(임베딩에 대한 코사인)와 어휘 레그(Postgres 전문 검색)를 Reciprocal Rank Fusion으로 융합하고, traverse는 엣지를 따라 이동합니다. 속성 값은 검색 가능한 표면에 포함되므로 타입화된 속성에만 저장된 사실도 찾을 수 있습니다.

• 데이터베이스가 강제하는 격리. 여러 스페이스와 스페이스 내 여러 주체(principal)는 잊혀질 수 있는 애플리케이션 검사가 아닌, 비슈퍼유저 역할로 실행되는 Postgres Row-Level Security로 분리됩니다. 서버는 NOBYPASSRLS 역할로 연결됩니다.

• LLM에 맞춰 설계된 범위 라우팅. 모든 범위는 자신이 관장하는 내용에 대한 설명을 담고 있습니다. 읽기 전용 scope_guide 도구는 이 라우팅 매니페스트를 반환하므로 에이전트는 쓰기 전에 새 메모리가 어디에 속해야 하는지 결정할 수 있습니다.

• 운영자 CLI와 MCP 도구 표면. 스페이스 부트스트래핑부터 토큰 발급, 데이터 가져오기, 팩 적용, 복원 검증에 이르기까지 모든 것을 위한 도구가 제공됩니다.

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

쓰기는 임베딩되어 유사도에 따라 병합 / 병합-링크 / 보류 / 신규 대역으로 분류되고 호출자의 신원으로 커밋됩니다. 읽기(search, get, traverse, briefing)는 RLS 하에서 실행되므로 호출자는 부여된 범위만 볼 수 있습니다. 팩은 스페이스의 노드 타입, 엣지 타입, 속성 스키마, 세션 시작 브리핑을 선언하므로 하나의 엔진이 다양한 형태의 메모리 애플리케이션을 서비스할 수 있습니다. 아키텍처 개요는 전체 쓰기 및 읽기 경로를 설명합니다.

빠른 시작

요구 사항: 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 클라이언트를 연결하세요. 설정 가이드는 Docker 없는 로컬 경로도 다룹니다.

클라이언트에서 사용하기

Engraphy는 MCP 서버이므로 클라이언트가 연결하여 도구를 호출합니다:

도구별 매개변수, 반환 값, 예시는 도구 참조를 참조하세요. 퍼스트파티 VS Code 확장은 vscode-extension/에 있습니다.

문서

• docs/ — 개발자 문서: 아키텍처, 설정, 팩, 도구 참조, 배포, 엔드투엔드 튜토리얼.

• design/ — 설계 문서 모음: 데이터 모델, 검색 및 중복 제거, 인증 및 테넌시, 운영, 팩/온톨로지 시스템, 벤치마크 하네스. 엔지니어링 설계 근거가 담긴 곳입니다.

• skills/ — LLM 에이전트가 Engraphy를 잘 사용하기 위해 로드할 수 있는 간결한 가이드(쓰기 및 중복 제거, 검색, 범위 및 가시성, 답변 규율).

요구 사항

• Postgres 16 및 pgvector(pgvector/pgvector:pg16 이미지에 둘 다 포함).

• Python ≥ 3.12.

• 마이그레이션용 dbmate(관리자 컨테이너에 번들됨; Docker 없는 경로에서만 PATH에 필요).

• 임베딩 모델 nomic-ai/nomic-embed-text-v1.5(384차원, ~523 MB, 첫 부팅 시 다운로드 및 캐시됨).

프로젝트 상태

v0.1.0. 스키마 및 강제 커널, 엔진 동작(중복 제거, 하이브리드 검색, 그래프 탐색, 브리핑), 인증 및 관리 기능을 갖춘 MCP 서버, 운영자 CLI가 구현되었으며 라이브 Postgres 테스트 스위트와 배포 아티팩트를 엔드투엔드로 검증하는 CI 작업으로 커버됩니다. 벤치마크 하네스(bench/, design/09)는 공개 장기 메모리 데이터셋에 대해 엔진을 실행합니다. 이는 변경 사항을 측정하기 위한 도구이지 마케팅 수치의 원천이 아닙니다.

라이선스

Engraphy는 Business Source License 1.1( LICENSE 참조)에 따라 라이선스가 부여됩니다.

• 허용: Engraphy를 읽고, 수정하고, 재배포하고, 자체 호스팅하고, 자체 애플리케이션 및 에이전트의 메모리 계층으로 프로덕션에서 사용할 수 있습니다.

• 금지: Change Date 이전에 Engraphy 자체를 제3자에게 호스팅 또는 관리형 서비스로 제공하는 것.

• Change Date: 2026-08-22 + 4년 (2030-08-22), 이 시점에 라이선스는 Apache License, Version 2.0으로 전환됩니다.

Copyright (c) 2026 Devon Clark.