MemoryGraph

에이전트가 관련 메모리를 찾았습니다. MemoryGraph는 그 메모리가 여전히 사실인지 알려줍니다.

MemoryGraph는 AI 에이전트의 신념을 위한 로컬 우선(local-first) 증거 및 개정 계층입니다. 소스 관찰을 보존하고, 주장을 시간 그래프로 표현하며, 주장이 왜 현재, 과거, 혹은 논쟁 중인지 설명합니다.

MVP 상태

결정적(deterministic) MVP가 실행 중입니다. 권위 있는 아키텍처는 00-architecture-index.md에서 시작하며, 구현된 커널은 다음을 포함합니다:

• 불변 소스 관찰.

• 정확한 증거 범위를 가진 타입 지정 엔티티 노드와 원자적(atomic)인 주장 엣지.

• 이중 시간(bi-temporal) 현재 및 멸과거 신념 조회.

• 명시적 확인(confirmation), 모순(contradiction), 원자적 대체(supersession).

• recall, history, explain 명령.

• 강력한 뱅크격리와 추가 전용(append-only) 변경 이벤트 로그.

• evidence, 규격, claim-version, idempotency, confidence, co가 포함된 provider-agnostic dream-proposal validator.

• 지속 가능한(durable) 드림 실행, 태스크, 제안, 검토 항목, 리스(lease), 이벤트 워터마크, 그리고 원자적 제안 커밋.

• 소스 데이터를 외부 모뎀으로 보내지 않고전체 드림 주기를 실행하는 결정적 메타데이터 프로바이더.

• MemoryRotBench 픽스처, 기준선(baseline), 검색 채점, 엔진 통합.

• 의존성 없는 로컬 기준선과 대체 가능한 임베더(embedder)를 갖춘 하이브리드 FTS/벡터 리콜.

• 신뢰할 수 없는 명령형(instruction-like) 콘텐츠에 대한 검색 중 격.

• 리스(lease), 하트비트 갱신, 재시도, replay-safe 리클이 가능한 크래시 복구 지원 Dream 워커.

• OpenAI 호환 구조화 출력으로 후보만 제안할 수 있는 프로바이더. *recall, record, explain, correct, forget 다섯 도구를 제공하는 STDIO MCP 서버.

• 사용자 승인을 거친 Codex JSONL 수집 및 프로젝트 범위 Codex 설치.

• 결정적이고 Obsidian과 호환되는 Markdown 리뷰 변환(projection).

• 성공과 실패를 유한하게 재사용 가능한 일급(procedural) 에피소드.

• 재현 가능한 no‑memory, Markdown, BM25, flat‑context, 외부/Graphify 벤치마크 어댑터.

• 크로스 플랫폼 CI, 패키지 검증, 실행 가능한 doctor 진단.

실제 파이썬 결정체는 현재 공개 MemoryRotBench 쿼 가 12/12, 프로덕션 카오스 contracts 7/7을 모두 통과. 이 커밋에서 리포지토리 테스트 스위트의 196개 통과 테스트가 확인됩니다. 첫 지문(fingerprint) 공개 매트릭스에서, 가장 강력한 단순 기준벤은 7/12를 통과한 반면 MemoryGraph는 12/12를 통과합니다.

빠른 시작

uv sync
uv run memorygraph init --database /tmp/memorygraph.db
uv run memorygraph doctor --database /tmp/memorygraph.db
uv run memorygraph bank create personal:founder --database /tmp/memorygraph.db
uv run memorygraph dogfood bootstrap --database /tmp/memorygraph.db
uv run memorygraph predicate define works_at \
  --bank personal:founder --cardinality one --volatility volatile \
  --database /tmp/memorygraph.db

증거를 기록하고, 나중에 주장으로 전환하세요:

OBSERVATION_ID=$(uv run memorygraph observe "Abrar works at Acme." \
  --bank personal:founder --source-key event:acme \
  --database /tmp/memorygraph.db)

CLAIM_ID=$(uv run memorygraph claim assert Abrar works_at Acme \
  --bank personal:founder --observation "$OBSERVATION_ID" \
  --database /tmp/memorygraph.db)

Python API에서도 임베디드 애플리케이션을 위해 confirm_claim, contradict_claim, supersede_claim, recall, history, explain 을 제공합니다.

성공적인 전략을 재사용하거나 알려진 실패를 피할 수 있도록 코딩 경험을 기록하세요—하지만 보편적으로 적용할 수 있다는 식으로 포장하지는 마세요:

memorygraph record-attempt "Run migrations before starting the worker" \
  --bank project:my-app --source-key attempt:migrate-worker \
  --task "start durable worker" --outcome success \
  --applicability-json '{"database":"sqlite"}'

드림 fresh

임베디드 프로바이더는 metadata.memorygraph에서 정형화된 후보를 읽고, 그래프 변경을 제안한 후, 증거와 시간 요소를 검증하고, 조건에 맞는 제안을 atomic 트랜잭션으로 커밋합니다. 모델 프로 바이어는 같은 후보만 제안할 수 있는 프로토콜을 사용하고, 데이터베이스 경로(쓰기)를 절대 갖지 않습니다.

PYTHONPATH=src:. uv run python examples/run_dream_cycle.py \
  --database /tmp/memorygraph-dream.db

uv run memorygraph dream status RUN_ID \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream reviews \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream rollback RUN_ID \
  --bank personal:founder --database /tmp/memorygraph-dream.db

CLI로 동일하게 사용하려면 observe --metadata-file FILE.json으로 후보를 보내고, memorygraph dream run --bank BANK 를 실행하세요. --mode dry_run은 제안만 검증하고 저장하며, 관찰을 소비하거나 주장을 변경하지 않습니다.

지속 실행(durable execution)을 위해서는 작업을 큐에 넣고 워커를 별도 프로세스로 처리하세요:

uv run memorygraph dream queue \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream worker \
  --bank personal:founder --database /tmp/memorygraph-dream.db

OpenAI 호환 Responses 엔드포인트를 사용하려면 설정된 키 변수를 지정하고, 큐와 워커 모두에 모델을 전달하세요. 프로바이더 출력은 엄격한 구조 데이터로 해석되며, 커밋되기 전에 동일한 결정적 검증 게이트를 통과합니다.

export OPENAI_API_KEY=...
uv run memorygraph dream queue --bank personal:founder \
  --provider-model YOUR_MODEL --database /tmp/memorygraph-dream.db
uv run memorygraph dream worker --bank personal:founder \
  --provider-model YOUR_MODEL --database /tmp/memorygraph-dream.db

Codex 연결

패키지 설치, 프로젝트 뱅크 초기화, 그리고 프로젝트 영역 MCP 설정을 추가하세요:

uv run memorygraph init
uv run memorygraph bank create project:my-app
uv run memorygraph install-codex --project .
uv run memorygraph probe-codex --project .

설치는 .codex/config.toml에 [mcp_servers.memorygraph] 블록을 생성하거나 수정하고, 그 블록을 현재 Python 환경의 memorygraph.mcp 모듈로 연결하며 Codex가 Story 쓰기 전 확인을 하도록 합니다. 전역 Codex 설정은 변경하지 않습니다. 다섯 가지 MCP 명령은 명시적 bank 범위를 요구합니다.

probe-codex는 프로젝트 설정을 확인하고 실제 MCP subprocess lifecycle을 실행합니다. 일시적인 테스트 DB 대신 구성된 프로젝트 DB를 테스트하려면 --project-database를 사용하세요.

세션 데이터 가져오기는 동의(opt-in)가 필요합니다. 각 JSONL 레코드에는 bank, session_id, turn_id, role, content, approved 항목이 있어야 하며, 승인되지 않은 레코드는 기본적으로 건너뜁니다:

memorygraph ingest-codex approved-session.jsonl

Dogfood Alpha

공식 오프라인은 다음의 6가지-arm 픽스처 매트릭스입니다:

PYTHONPATH=src:. uv run python examples/run_dogfood_fixture_matrix.py

실제 프로젝트에서는 먼저 운영 contract를 부트스트랩하세요:

uv run memorygraph dogfood bootstrap \
  --database .memorygraph/memory.db \
  --bank project:my-app \
  --workspace my-app

픽스처 매트릭스는 다음의 암(arm) 상태를 실행합니다:

• no_memory

• markdown

• memorygraph_graph_only

• memorygraph_gated_dream

• memorygraph_always_dream

• graphify_compatible

다음 항목을 측정합니다: 태스크 통과 여부, 유용한 리콜 정밀도, 금지·오래된 리 콜 유출, 반복 실수, 레이턴시, 토큰 추정치, 툴 사용, 재시도, 예상 비용 필드, Dream review 로드. 결과는 benchmarks/reports/dogfood-offline-mvp.json과 추가 전용 로그 benchmarks/reports/dogfood-offline-mvp.jsonl에 기록됩니다. 태스크 통과는 쿼리 기대치를 따르고, Dream 리뷰 부하는 추적 대상이지만 별도 항목으로 남습니다.

보고 2026-08-22 현재 오프라인 픽스처 결과:

• memorygraph_always_dream: 3/3

• memorygraph_graph_only: 1/3

• memorygraph_gated_dream: 1/3

• graphify_compatible: 1/3

• markdown: 1/3, 금지된 조각 누출이 있음

graphify_compatible은 프로토콜 어댑터입니다—외부 retriever가 동일한 매니페스트, 시간 범위, 채점 계약으로 경쟁하도록 합니다. 이 어댑터가 실제 Graphify 비교를 이미 완료했다고 주장하는 것은 아닙니다.

Obsidian에서 리뷰

현재 주장, 정확한 출처(provenance), 관계, 그리고 Dream 검토 대기열이 포함된 Markdown 저장 소를 생성하세요:

memorygraph project-obsidian --bank project:my-app \
  --output .memorygraph/obsidian

이 Markdown은 일시적이며 manifests가 관리입니다. SQLite 관찰 기록과 append-only 이벤트 로그는 항상 신뢰할 수 있는 원천으로 남습니다. 생성된 노트를 편집해도 memory 가 조용히 변하지 않습니다.

왜 그래프인가?

그래프는 에이전트에게 확장 가능한 구조를 힌트 합니다: 주체를 노드로, 예를 들어 Abrar --works_at--> Stripe 같은 주장을 typed edge를 나타냅니다. MemoryGraph는 edge를 불변의 진실로 취급하지 않습니다. 각 주장 버전에는 유효 기간, 시스템 시간, 수명주기, 출처, 소스 증거가 저장됩니다. 그것이 유용한 메모리 그래프와 낡은 팩트 저장소 사이의 차이입니다.

개발

재현 스크립트를 실행하세요:

uv sync --extra dev
uv run pytest
uv run ruff check .
PYTHONPATH=src:. python examples/run_memoryrotbench_memorygraph.py
PYTHONPATH=src:. python examples/run_memoryrotbench_chaos_memorygraph.py
python examples/run_memoryrotbench_baseline_matrix.py
PYTHONPATH=src:. uv run python examples/run_dogfood_fixture_matrix.py

기대 결과: /12 공용 리콜 사례와 7/7 프로덕健康 카오스 케이스를 통과. 매트릭스는 불변의 코퍼스 보존형·평가자 지문이힌 기록을 benchmarks/reports/public-baseline-matrix.jsonl에 추가합니다. --graphify-command 를 제공하면 정확히 동일한 공개 코퍼스와 채점 계약에 대해 외부 Graphify 어댑터를 실행할 수 있습니다.

다음 상품 레이어

다음 단계는 여전히 실제 증명입니다: 모델 기반의 라이브 dogfood 세션, Graphify와 진짜 사과(head‑to‑head) 비교, 그리고 실제 코딩 작업에서 파트너와의 사용입니다. 파이프라인 전체의 삭제 잔여 물질은 감사 및 보고됩니다. 방향을 다시 쓰지 않고 안전하게 지울 수 없는 정체성 잔여 정보는 숨기지 않고 노출합니다. Dream 검증기는여전히 모든 provider와 worker가 통과해야 할 정문으로 남습니다.

Apache-2.0 라이선스하에 배포됩니다.