agent-context-substrate

기반이 자산이며, 모델은 교체 가능한 클라이언트입니다.

git clone https://github.com/thomaskawas/agent-context-substrate.git
cd agent-context-substrate
make setup && make demo

요구 사항: Python 3.12+, Docker, make. make setup은 venv를 생성하고 의존성을 설치합니다. 데모가 CPU에서 실행되고 CUDA 휠을 건너뛰므로 약 1.4GB이며, 느린 연결에서는 몇 분이 걸릴 수 있습니다. 데이터베이스는 127.0.0.1:5432에 바인딩되므로 해당 포트를 이미 사용 중인 프로세스를 중지하세요.

왜 존재하는가

저는 AI 에이전트로 장기 프로젝트를 구축하며, 매 세션 시작 시 컨텍스트를 다시 설정하는 것이 가장 자주 치르는 비용이었습니다. 같은 파일을 업로드하고, 같은 결정을 다시 설명하고, 모델이 이미 두 번 본 자료로 창의 유용한 부분이 채워지는 것을 지켜보았습니다. 더 나은 모델이 출시되어도 그 어떤 것도 이전되지 않았습니다. 문제는 컨텍스트가 없다는 것이 결코 아니었습니다. 문제는 컨텍스트에 주소를 지정할 수 없다는 것이었습니다. 질문을 던지고 그에 답하는 것만 돌려받을 방법이 없어서, 모든 것을 보내고 기대할 수밖에 없었습니다. 해결책은 컨텍스트를 세션에 가져가는 무언가로 취급하는 것을 멈추고, 쿼리하는 무언가로 취급하기 시작하는 것이었습니다.

AI 에이전트를 위한 모델 독립적 메모리 기반의 참조 구현입니다. 프로젝트 메모리는 모델 외부의 쿼리 가능하고 버전 관리되는 저장소에 있으며, 하나의 MCP 게이트웨이를 통해 노출됩니다. 모델을 교체하세요. 모든 것을 유지합니다. 오늘은 Claude, 내일은 Gemini 또는 GPT, 그 아래에는 동일한 프로젝트 메모리가 있습니다. 매 세션에 기록을 붙여넣는 대신, 검색은 현재 작업에 실제로 필요한 작은 레코드 집합을 선택합니다.

이 저장소는 해당 패턴의 클린룸 참조 구현으로, 합성 코퍼스에 대해 처음부터 작성되어 이 페이지의 모든 숫자가 고정된 의존성으로 깨끗한 클론에서 재현됩니다. 이는 패턴이지, 제가 직접 작업에 사용하는 시스템이 아닙니다.

API 키가 필요 없습니다. make demo는 전적으로 로컬 구성 요소로 실행됩니다. 고정된 로컬 모델(이름 및 리비전)이 기본 어댑터 프로필인 local입니다(make warmup은 make demo가 자동으로 실행하며, 약 180MB를 한 번 사전 다운로드합니다). 밀폐된 무다운로드 deterministic 프로필은 테스트와 상시 CI 게이트를 지원합니다.

Related MCP server: AI Memory MCP Server

구조

src/acs/adapters/base.py는 코드로 표현된 핵심 주장입니다. 모든 외부 기능이 뒤에 위치하는 네 개의 작은 인터페이스입니다. src/acs/store/는 메모리를 기록 시스템(버전 관리, 감사 가능, 진정한 삭제 가능)으로 취급합니다. src/acs/retrieval/는 작고 개별적으로 테스트 가능한 단계로 구성된 파이프라인입니다. eval/은 게이트입니다. 변경 사항은 baseline.lock.json을 일치시키거나 능가할 때만 출시되며, 그렇지 않으면 출시되지 않습니다.

설계 근거는 docs/adr/에 있습니다. 9개의 결정 기록입니다. 대부분은 반 페이지이며, 세 개는 더 길게, 논증이 공간을 필요로 했습니다.

또한 docs/에는 다음이 있습니다. 각 계층이 존재하는 이유에 대한 architecture.md, 적대적 경계와 각 방어가 위치한 곳에 대한 threat-model.md, 나머지가 따르는 규칙에 대한 principles.md, 그리고 이 저장소가 따른 빌드 순서에 대한 build-your-own.md가 있습니다.

시연 내용

• 수집은 한 번에 두 가지 표현을 작성합니다. 유사성을 위한 임베딩, 구조를 위한 엔터티/관계 그래프입니다. 모든 문서는 임베딩되며, 관계를 명시하지 않는 문서는 엣지를 기여하지 않습니다.

• 검색은 4단계 파이프라인입니다. 조정 가능한 혼합의 하이브리드 벡터 + 전문 검색, 다중 쿼리 융합(RRF), 교차 인코더 재순위화, 그리고 그래프가 재순위화된 목록을 재정렬하는 엔터티 앵커 파티션으로, 주제별 재순위화기가 유사한 이름의 형제 구성 요소와 혼동하는 것을 방지합니다. 소비자별 검색 프로필은 코드가 아닌 데이터입니다.

• 거버넌스: 검색 변경은 잠긴 평가 기준을 일치시키거나 능가할 때만 출시됩니다. 메모리는 SCD2 버전 관리로 시간 이동 읽기를 지원하며, 제거는 진정으로 삭제(벡터 포함)하고, 감사 로그는 데이터베이스 수준에서 변경을 거부합니다.

• 접근: 하나의 MCP 게이트웨이가 모든 MCP 클라이언트에 기반을 제공하며, 호출자별로 범위가 지정됩니다. 격리된 연구 루프는 인용 필수 쓰기 백으로 공백을 채웁니다.

• 이식성: 모든 공급자는 어댑터 뒤에 있으며, 임베더는 의도적으로 고정됩니다.

계보 ID와 타임스탬프는 모두 make history에서 가져옵니다. 인자 없이 실행하면 현재 메모리와 해당 ID를 나열하고, LINEAGE=<id>를 사용하면 하나의 메모리 버전 체인을 탐색하며 각 버전의 유효 기간을 출력합니다. 해당 기간은 ISO 타임스탬프이므로 붙여넣은 TS=는 실제로 읽은 버전으로 해석되며, 그 전후 1초의 버전이 아닙니다. ID는 클론마다 생성되므로 여기에 표시된 것과 일치하지 않습니다.

make purge는 진정으로 삭제합니다(제거된 주제에 속하는 골든 세트 대상 포함). 따라서 제거된 코퍼스에 대한 벤치마크는 조용히 낮은 재현율을 보고하는 대신 불완전으로 실행을 거부합니다. make demo는 깨끗한 코퍼스로 재설정합니다.

이 페이지의 모든 벤치마크 숫자는 시드된 합성 코퍼스에 대한 절제(corpus/generate.py)에서 비롯되며, 깨끗한 클론에서 재현 가능하고 CI에서 게이트됩니다(모든 푸시에서 결정적 프로필, bench-local 레이블에서 로컬 프로필). 잠긴 기준은 코퍼스 다이제스트도 잠급니다. 절대값이 아닌 델타를 읽으세요. 합성 코퍼스의 recall@5 / mrr@5는 각 단계가 기여하는 바를 보여주며, 실제 품질을 나타내지 않습니다. 단계가 델타를 얻는 위치를 보려면 .venv/bin/python eval/run_benchmark.py --by-family를 실행하세요.

절제, 로컬 프로필

각 단계는 다른 것을 얻습니다. 이는 더 나은 검색기 하나보다 파이프라인을 주장하는 근거입니다. tests/test_readme_table.py는 이 표와 eval/baseline.lock.json이 불일치하면 실패하므로, 표는 게이트가 강제하는 숫자에서 벗어날 수 없습니다. 게이트는 바닥이므로 메트릭을 개선하는 변경은 통과하며, 여기의 숫자는 make lock-baseline으로 의도적으로 기준을 다시 잠글 때까지 유지됩니다. 그러면 이 표는 일치하도록 업데이트될 때까지 실패합니다. 로컬 프로필, 120개의 골든 쿼리, k=5, 1단계 병합 rank, 코퍼스 다이제스트 ad7bf7ca. make demo로 재현하세요.

이 숫자가 지지하는 것과 지지하지 않는 것, 모델 경로 비교가 곡선이 아닌 경계인 이유를 포함한 내용은 docs/limitations.md에 설명되어 있습니다.