에이전트 메모리 브리지

간체 중국어

실제 세션을 재사용 가능한 엔지니어링 메모리로 변환하는 코딩 에이전트용 MCP 네이티브 메모리 계층입니다.

Codex를 우선으로 구축되었습니다.

에이전트 메모리 브리지는 일반적인 채팅 기록에서 손실되는 다음 정보를 캡처합니다:

지속적인 결정
알려진 수정 사항
세션 간 핸드오프
재사용 가능한 주의 사항(gotchas)
압축된 도메인 지식

핵심 아이디어는 간단합니다. 메모리 계층을 작고 신뢰할 수 있으며 검사 가능하게 유지하는 것입니다. 상위 수준의 오케스트레이션은 그 위에 배치하십시오.

흥미로운 부분은 단순히 지속성만이 아닙니다. 자동 메모리 형성 기능입니다:

세션은 재사용 가능한 learn이 됩니다.
반복되는 실패는 gotcha가 됩니다.
학습 내용의 클러스터는 압축된 domain-note가 됩니다.

이 프로젝트가 존재하는 이유

대부분의 에이전트 메모리 시스템은 다음 세 가지 패턴 중 하나로 흐릅니다:

하나의 앱이나 모델 내에 갇힌 메모리
검색 기본 사항이 증명되기 전에 무거운 호스팅 인프라 사용
재사용 가능한 운영 지식 대신 기록(transcript)을 덤프하는 방식

에이전트 메모리 브리지는 더 좁은 길을 택합니다:

첫날부터 MCP 네이티브
로컬 우선 런타임
무거운 인프라 대신 SQLite + FTS5 사용
세션 추적에서 재사용 가능한 메모리로의 자동 승격

단순한 저장이 아닙니다. 메모리 형성 파이프라인입니다:

session -> summary -> learn -> gotcha -> domain-note

포지셔닝

에이전트 메모리 브리지는 의도적으로 좁은 범위를 가집니다.

SDK, 대시보드, 커넥터 및 다중 표면 애플리케이션 지원을 포함하는 더 넓은 메모리 플랫폼을 원하신다면 OpenMemory나 Mem0와 같은 프로젝트가 그 형태에 더 가깝습니다.

이 프로젝트는 의도적으로 다릅니다:

일반적인 메모 저장이 아닌 코딩 에이전트 워크플로우를 위해 구축되었습니다.
MCP 표면을 의도적으로 store와 recall로 작게 유지합니다.
요약을 최종 결과물로 취급하는 대신 원시 세션 출력을 기계가 읽을 수 있는 압축된 메모리로 승격합니다.
기본적으로 로컬 우선이며 검사 가능합니다.

더 긴 포지셔닝 노트는 docs/COMPARISON.md를 참조하십시오.

작동 방식

런타임에는 네 가지 주요 구성 요소가 있습니다:

MCP 서버
- store와 recall 노출
감시자(watcher)
- Codex 롤아웃 파일 관찰
- session-seen, checkpoint, closeout 기록
반사(reflex)
- 요약을 learn, gotcha, signal로 승격
통합(consolidation)
- 반복되는 learn 및 gotcha 기록을 도메인 노트로 합성

이를 통해 시스템을 이해하기 쉽게 유지합니다:

원시 세션은 최종 메모리가 아닙니다.
요약은 최종 메모리가 아닙니다.
지속적인 메모리는 기계 우선입니다.
합성은 승격 후에 발생합니다.

빠른 시작

요구 사항:

Python 3.11+
MCP가 활성화된 Codex
FTS5 지원이 포함된 SQLite

1. 설치

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]

2. 브리지 구성 생성

config.example.toml을 다음 위치로 복사합니다:

$CODEX_HOME/mem-bridge/config.toml

권장 설정:

라이브 SQLite 데이터베이스를 각 머신에 로컬로 유지
필요한 경우 NAS나 공유 스토리지에 공유 프로필 또는 소스 볼트 유지
진정한 다중 머신 라이브 쓰기를 원할 경우 나중에 호스팅된 백엔드로 이동

3. Codex에 MCP 서버 등록

$CODEX_HOME/config.toml에 다음을 추가합니다:

[mcp_servers.agentMemoryBridge]
command = "D:\\path\\to\\agent-memory-bridge\\.venv\\Scripts\\python.exe"
args = ["-m", "agent_mem_bridge"]
cwd = "D:\\path\\to\\agent-memory-bridge"

[mcp_servers.agentMemoryBridge.env]
CODEX_HOME = "%USERPROFILE%\\.codex"
AGENT_MEMORY_BRIDGE_HOME = "%USERPROFILE%\\.codex\\mem-bridge"
AGENT_MEMORY_BRIDGE_CONFIG = "%USERPROFILE%\\.codex\\mem-bridge\\config.toml"

4. 서비스 시작

MCP 서버 시작:

.\.venv\Scripts\python.exe -m agent_mem_bridge

백그라운드 브리지 서비스 실행:

.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

한 번만 주기 실행:

$env:AGENT_MEMORY_BRIDGE_RUN_ONCE = "1"
.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

선택적 시작 설치:

.\scripts\install_startup_watcher.ps1

선택 사항: 로컬 Docker 이미지 빌드

docker build -t agent-memory-bridge:local .
docker --context desktop-linux run --rm -i agent-memory-bridge:local

컨테이너 진입점은 python -m agent_mem_bridge로 stdio MCP 서버를 시작합니다.

핵심 API

MCP 표면은 의도적으로 작습니다:

store
recall

일반적인 store 필드:

namespace
content
kind
tags
session_id
actor
title
correlation_id
source_app

일반적인 recall 필드:

namespace
query
kind
tags_any
session_id
actor
correlation_id
since
limit

일반적인 네임스페이스

project:<workspace>
global
domain:<name>
팀이 원하는 경우 가져온 프로필 네임스페이스

프레임워크는 프로필에 구애받지 않습니다. 특정 운영자 프로필을 위에 계층화할 수 있지만, 브리지 자체는 하나의 페르소나나 프로토콜에 묶여 있지 않습니다.

일상적인 사용

의도된 계층화는 다음과 같습니다:

시스템 수준 운영자 프로필
시스템 수준 메모리 기질: agentMemoryBridge
프로젝트 로컬 재정의: AGENTS.md

시작 프로토콜은 docs/STARTUP-PROTOCOL.md에 문서화되어 있습니다.

요약하자면:

전역 운영 메모리 호출(recall)
관련 전문 메모리 호출
워크스페이스가 존재하는 경우 project:<workspace> 호출
이슈와 같은 작업의 경우 외부 검색 전에 로컬 메모리와 주의 사항 확인
호출된 구현 세부 정보를 신뢰하기 전에 라이브 코드 검사

유용한 명령어

테스트 실행:

.\.venv\Scripts\python.exe -m pytest

stdio 스모크 테스트 실행:

.\.venv\Scripts\python.exe .\scripts\verify_stdio.py

벤치마크 실행:

.\.venv\Scripts\python.exe .\scripts\run_benchmark.py

브리지 상태 확인 실행:

.\.venv\Scripts\python.exe .\scripts\run_healthcheck.py --report-path .\examples\healthcheck-report.json

최신 롤아웃에서 체크포인트 강제 실행:

.\.venv\Scripts\python.exe .\scripts\sync_now.py

프로젝트 구조

저장소는 의도적으로 작습니다:

src/agent_mem_bridge/   canonical implementation
scripts/                operational entrypoints
tests/                  verification
docs/                   design and roadmap
examples/               sanitized demo artifacts

가장 중요한 파일:

설계 선택

작은 MCP 표면

브리지는 store와 recall만 노출합니다. 이는 계약을 안정적으로 유지하고 통합하기 쉽게 만듭니다.

로컬 우선 런타임

공유 네트워크 스토리지의 SQLite는 신뢰성 함정이므로 라이브 DB는 기본적으로 로컬에 유지됩니다.

기계 우선 메모리

에이전트가 주 독자이므로 메모리는 다음을 선호합니다:

압축된 필드
안정적인 태그
낮은 토큰 비용

세련된 산문보다 위 항목을 우선합니다.

계층화된 승격

시스템은 다음 방향으로 이동하려고 합니다:

summary
learn
gotcha
domain-note

원시 요약을 최종 결과물로 취급하는 대신 위와 같이 승격합니다.

상태

현재 기반은 작동 중입니다:

Codex에서 MCP 자동 로드 작동
프로젝트 및 세션 동기화 작동
호출 우선 워크플로우 작동
반사 승격 작동
1차 도메인 통합 작동

현실 점검 및 로드맵:

프로필 가져오기

프레임워크는 가져온 운영자 프로필을 호스팅할 수 있지만, 프레임워크 자체는 프로필에 구애받지 않습니다.

문서

라이선스

MIT. LICENSE를 참조하십시오.

Agent Memory Bridge