Ebb — 에이전트 우선 지식 그래프

AI 에이전트를 위한 장기 기억, 그래프로 구축됨. 관련성은 최근성 가중 연결 강도: 지식을 재사용하면 유지되고, 사용하지 않으면 감쇠되어 아카이브되며, 인간이 승인하기 전까지는 아무것도 삭제되지 않음. 임베디드 (인프라 제로) 또는 Neo4j(프로덕션)에서 실행.

이 시스템의 기반이 되는 두 메커니즘 — 연결 가중 관련성과 시간 감쇠 — 은 네이티브 그래프 연산이며, 둘 다 깊은 선례가 있음 (PageRank/중심성; 인지과학의 ACT-R 기저 활성화 및 확산 활성화; 간격 반복 망각 곡선). 이는 에이전트 메모리를 겨냥한 그 계보의 작고 정직한 구현임.

이렇게 만든 이유

1. 엔진과 인터페이스는 분리되어 있음. 그래프 저장소는 작은 인터페이스(GraphStore) 뒤에 있음. 에이전트와 점수 계산 로직은 특정 데이터베이스를 건드리지 않으므로, 오늘은 임베디드 엔진에서 동일한 그래프를 실행하고 나중에 환경 변수 하나로 Neo4j로 전환할 수 있음.

2. 관련성은 원시 연결 수가 아닌 최근성 가중. "연결이 많을수록 관련성이 높다"는 오래되고 많이 참조된 데이터를 영원히 보상함 — 시스템이 제거하려는 바로 그 오래된 데이터 문제. 여기서 각 엣지의 관련성 기여도는 연결이 마지막으로 강화된 시점을 기준으로 한 시간 감쇠 계수가 곱해짐. 어제 강화된 엣지는 거의 전체로 계산되고, 6개월 전에 마지막으로 접촉된 엣지는 거의 아무것도 계산되지 않음. 연결을 재사용하면(recall/reinforce) 시계가 리셋됨 — 따라서 관련성은 실제로 활성화된 것을 추적하고, 오래된 지식은 스스로 가라앉음.

데모 시드 그래프(python -m ebb.demo)에서의 증거:

node                             raw#   activation
decision:outcome-pricing            3        6.116   <- fresh, few links, ranks #1
decision:seat-pricing              11        3.077   <- MOST links, ranks #3
...
note:analysis-* (x10)               1        0.051   <- decayed -> archived (tier 4)

대체된 좌석당 결정은 그래프에서 가장 높은 원시 연결 수를 가지고도 여전히 3위에 머물며, 연결 수가 3분의 1인 새로운 결정보다 뒤처짐. 원시 연결 수는 졌고, 최근성이 이겼음.

Related MCP server: Memory Engine MCP

구성 요소

• 그래프 모델 — 모든 노트, 결정, 회의, 사람, 클라이언트, 사실은 노드; 모든 참조는 타임스탬프가 있는, 유형화된, 가중치가 있는 엣지.

• 점수 계산 엔진(scoring.py) — 최근성 가중 활성화, 지수 감쇠(반감기 구성 가능), 확산 활성화 1홉(PageRank의 휴대용 대체), 계층 할당. 순수 함수, 완전히 단위 테스트됨.

• 4개 아카이브 계층 — 1 핫(기본 recall) · 2 웜(더 깊은 recall) · 3 콜드(아카이브됨, 요청 시에만) · 4 프로즌(삭제 전 인간 승인 대기 중). 고정된 노드는 자동 아카이브되지 않음.

• MCP 서버(mcp_server.py) — 에이전트 인터페이스: remember, recall, connect, reinforce, forget, neighbors, pin, maintain, review_queue, stats.

• 두 백엔드 — KuzuStore(임베디드, 기본값) 및 Neo4jStore (프로덕션), 동일한 인터페이스, 동일한 Cypher 형태.

빠른 시작 (임베디드 — 인프라 제로)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m ebb.demo      # narrated end-to-end walkthrough
pytest -q                 # 11 tests, all green

Docker 없음, 서버 없음, 포트 없음. Kùzu는 인프로세스 그래프 데이터베이스이므로 Ebb는 그냥 폴더(./ebb_db)임.

MCP 클라이언트에 연결 (예: Claude Desktop)

1. claude_desktop_config.example.json에서 ebb 블록을 클라이언트의 MCP 구성에 복사하고 절대 경로를 수정.

2. 클라이언트를 다시 시작. ebb 도구가 도구 메뉴에 나타남.

3. 에이전트는 이제 세션 간에 remember로 기억하고, 관련된 것을 recall하며, 계속 사용하는 것을 reinforce할 수 있음 — 감쇠와 아카이빙은 자동 처리됨.

프로덕션 모드 (Neo4j)

docker compose up -d      # Neo4j + Graph Data Science + APOC
EBB_BACKEND=neo4j NEO4J_PASSWORD=brainbrain python -m ebb.demo

동일한 코드, 동일한 동작. Neo4j에서는 추가로 GDS 라이브러리를 얻으므로 scoring.py의 확산 활성화 패스는 규모가 필요할 때 실제 PageRank / 중심성 / 커뮤니티 탐지로 승격될 수 있음. (Neo4j 백엔드의 Cypher는 완전히 테스트된 Kùzu 백엔드를 미러링함; 프로덕션에서 신뢰하기 전에 라이브 인스턴스에서 pytest를 실행.)

모델 요약

노드의 활성화 = Σ (edge.weight × decay(age_since_last_reinforced)) + 읽기-최근성-보너스, 이웃에서 동일한 감쇠 1홉이 추가됨. 감쇠는 반감기 (기본 30일, 조정 가능). 계층은 가장 활성화된 비고정 노드에 대해 정규화된 활성화로 잘림. recall은 이 활성화를 쿼리 텍스트 일치와 혼합하고 각 결과가 표면화된 이유를 반환. 모든 것은 한 곳에서 조정 가능 — ebb/scoring.py::Config.

수집 어댑터 작성

Ebb는 소스에 구애받지 않음: remember/connect를 호출하는 모든 것이 피드할 수 있음. 소스(노트 폴더, 위키, 이슈 트래커)는 문서를 노드로, 링크/언급을 엣지로, 편집 타임스탬프를 최근성 시계로 매핑하여 그래프가 됨. 어댑터와 해당 데이터는 저장소 밖에 유지.

구조

src/ebb/
  model.py        # Node, Edge, tiers
  scoring.py      # decay, activation, spreading, tiering  <- the core
  store.py        # GraphStore interface
  kuzu_store.py   # embedded backend (default)
  neo4j_store.py  # production backend
  engine.py       # Brain: remember/recall/connect/reinforce/maintain/...
  mcp_server.py   # agent-facing MCP tools
  seed.py         # fictional demo graph
  demo.py         # narrated walkthrough
tests/            # 11 tests: scoring + end-to-end
docker-compose.yml

라이선스

MIT — LICENSE 참조.