mcncarl/agent-memory-vault

Markdown-first shared memory vault for Claude Code and Codex with SQLite, Zvec, Git, closeout, and audit

Agent Memory Vault – Claude Code, Codex 및 유사한 AI 코딩 에이전트를 위한 로컬, Git 백업 장기 기억 저장소

정의 – AI 코딩 에이전트가 자신의 머신에서 지속적이고 감사 가능한 지식 기반을 유지할 수 있게 하는 Python 기반 툴킷입니다. 진실의 원천은 일반 텍스트 Markdown 디렉토리(볼트)입니다. Git이 모든 변경 사항을 추적하고, SQLite가 빠른 키워드/FTS 검색을 제공하며, 선택적 로컬 임베딩 모델(EmbeddingGemma + Zvec)이 의미 검색을 추가합니다. 모든 데이터는 비공개로 유지됩니다. 공개 저장소에는 재사용 가능한 스크립트와 템플릿만 포함됩니다.

중요성 – 현재 AI 코딩 어시스턴트(Claude Code, Codex 등)는 현재 채팅 세션에서 말한 내용만 기억합니다. 프로젝트가 여러 세션에 걸쳐 있을 때 중요한 사실, 결정, 코드 스니펫이 손실됩니다. Agent Memory Vault는 이러한 에이전트에게 공유되고 버전 관리되는 메모리를 제공합니다. 이 메모리는:

세션 간에 지속됩니다.
모든 쓰기가 검토되고 서명되며 Git에 기록되도록 보장합니다.
여러 에이전트(Codex, Claude, 타사 "Ailu")가 안전하게 동시에 사용할 수 있습니다.
권위 있는 Markdown을 변경하지 않고 키워드 및 선택적 벡터 검색을 모두 제공합니다.

핵심 구성 요소

구성 요소	역할
`templates/vault/`	개인 폴더에 복사할 수 있는 준비된 Markdown 레이아웃.
`scripts/bootstrap.py`	새 볼트를 만들고, 개인 Git 저장소를 초기화하고, 초기 `INDEX.md`를 작성합니다.
`scripts/memoryctl`	에이전트가 검색, 검색, 쓰기, 마이그레이션, 상태 점검 등에 사용하는 통합 명령줄 인터페이스.
`scripts/agent_memory_index.py`	볼트에서 SQLite FTS 인덱스를 구축합니다.
`scripts/agent_memory_search.py`	키워드 + 선택적 벡터(Zvec) 검색을 실행하고 순위가 매겨진 후보를 반환합니다.
`scripts/agent_memory_retrieve.py`	선택한 Markdown 파일을 다시 열고, 해시를 검증하고, 제한된 발췌문을 반환합니다.
`scripts/agent_memory_write.py`	펜싱 토큰과 Git 커밋을 사용하여 읽기-준비-승인-적용 쓰기 흐름을 구현합니다.
`scripts/agent_memory_migrate.py`	명시적 백업 및 감사 단계를 통해 볼트 스키마(v1 → v4) 업그레이드를 처리합니다.
`scripts/agent_memory_closeout.py`	쓰기를 완료하고, Git에 영수증을 기록하고, 감사 원장을 업데이트합니다.
`scripts/agent_memory_doctor.py`	볼트, 인덱스 및 런타임 구성을 검증하는 종단 간 상태 점검 스위트.

작동 방식(높은 수준의 흐름)

볼트 만들기 – bootstrap.py는 개인 디렉토리를 만들고, Markdown 템플릿을 복사하고, 새 Git 저장소에 커밋합니다.
인덱스 – agent_memory_index.py는 볼트를 스캔하고 SQLite FTS 테이블을 구축합니다. 선택적으로 Zvec 벡터 인덱스가 추가됩니다.
검색 – 에이전트는 memoryctl --actor <agent> search "query"를 호출합니다. CLI는 키워드 일치를 병합하고, 활성화된 경우 벡터 점수(하이브리드 RRF)도 병합하여 memory_id 목록을 반환합니다.
검색 – memoryctl retrieve --view section …은 정확한 파일을 다시 열고, 저장된 해시가 현재 파일과 일치하는지 확인하고, 안전한 발췌문을 반환합니다.
쓰기 – 쓰기 프로토콜은 다음과 같습니다:
- write read-target → 현재 바이트와 임대 토큰을 가져옵니다.
- write prepare → 새 버전을 제안하고 단조 증가하는 펜싱 토큰을 얻습니다.
- 승인(사람 또는 정책) → 제안을 승인합니다.
- write apply → CLI는 임대, 토큰, Git 베이스를 검증한 다음 파일을 원자적으로 교체하고 영수증을 기록합니다.
- closeout → 최종 감사 항목 및 Git 커밋.
마이그레이션/업그레이드 – memoryctl --actor migration …은 계획된 읽기 전용 마이그레이션을 실행하고, 상태 DB를 백업하고, 명시적 검토 후에만 변경 사항을 적용합니다.

주요 안전 보장

Git 백업 불변성 – 모든 수락된 변경은 서명된 Git 커밋입니다. 볼트는 롤백할 수 있습니다.
펜싱 토큰 – 오래된 작성자가 최신 제안을 덮어쓰는 것을 방지합니다.
감사 원장 – 모든 읽기, 쓰기 및 상태 전환은 해시, 타임스탬프 및 위험 분류와 함께 기록됩니다.
개인정보 우선 로깅 – 검색 로그에는 해시와 분류만 저장되며 원시 쿼리나 사용자 식별 데이터는 절대 저장되지 않습니다.
명시적 위험 클래스 – action_sensitive로 표시된 작업은 더 엄격한 증거가 필요하며 다운그레이드할 수 없습니다.

설치(빠른 시작)

# 저장소 복제
git clone https://github.com/mcncarl/agent-memory-vault.git
cd agent-memory-vault

# POSIX 진입점 설치(계획 후 적용)
python3 scripts/install-posix.py --plan \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks --json
python3 scripts/install-posix.py --apply \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks \
  --launchagent-backup-dir "$HOME/.config/agent-memory/backups/launchagent-NEW" \
  --json

--plan 단계는 발생할 일을 읽고 보고만 합니다. --apply는 실제 부트스트랩, Git 초기화 및 인덱스 생성을 수행합니다.

AI 에이전트의 일반적인 사용법

# 관련 프로젝트 노트 검색
scripts/memoryctl --actor codex search "deployment boundary" --limit 5

# 특정 섹션을 안전하게 검색
scripts/memoryctl --actor codex retrieve --view section \
  --file "项目/example.md" --project-id example-app \
  --section-id s0002 --expected-sha256 '<outline-sha256>' --json

# 새 결정 기록 제안(에이전트가 마크다운을 준비하고 사람에게 승인 요청)
scripts/memoryctl --actor codex write read-target --json <<'JSON'
{"schema_version":2,"target_relative_path":"决策/2024-10-17-deploy.md","app_id":"example-app","project_id":"example-project"}
JSON
# …사람이 제안 JSON을 검토한 후:
 scripts/memoryctl --actor codex write apply <proposal-id> --json

모든 쓰기는 동일한 게이트 흐름을 거치므로 볼트에 검토되지 않은 편집이 포함되지 않도록 보장합니다.

선택적 의미 검색 – 벡터 기반 검색이 필요한 경우 추가 환경을 설치하세요:

python3 -m venv .venv-vector
.venv-vector/bin/pip install -r requirements-vector.lock

벡터 계층은 후보 ID만 제공합니다. 권위 있는 SQLite/Markdown 계층이 최종 필터링을 수행합니다.

지원 플랫폼 – macOS, Linux(POSIX 설치 프로그램) 및 Windows 10/11(PowerShell 설치 프로그램). 핵심 코드는 순수 Python 3.10+이며 외부 서비스가 없습니다. 모든 데이터는 로컬 머신에 유지됩니다.

성숙도 – 저장소에는 전체 테스트 스위트(scripts/run_tests_isolated.py)와 "doctor" 상태 점검 명령이 포함되어 있습니다. 설계는 로컬 AI 에이전트를 위한 프로덕션 등급 안전성을 목표로 하지만, 여전히 자체 환경에서 Claude Code, Codex 또는 유사한 에이전트를 실행하는 개발자를 위한 틈새 자체 호스팅 도구입니다.

결론 – Agent Memory Vault는 여러 AI 코딩 에이전트가 안전하게 읽고 쓸 수 있는 비공개, 버전 관리, 검색 가능한 지식 기반을 제공합니다. 일시적인 채팅 세션 메모리와 지속적인 프로젝트 문서 사이의 격차를 해소하면서 데이터를 사용자 통제 하에 유지합니다.