LeoYeAI/talewell
Plugin-first long-term memory for agent platforms — reference implementation of AMP (Agent Memory Protocol).
TL;DR
Talewell은 플러그인 우선의 Git 기반 AI 에이전트용 장기 기억 시스템입니다. 각 기억 레코드를 Git 저장소 내의 일반 텍스트 Markdown 파일로 저장하여, 벡터 데이터베이스 없이도 완전한 버전 기록, 차이점 비교, 감사 기능을 제공합니다. 이 시스템은 간단한 **AMP (Agent Memory Protocol)**를 사용하여 모든 호스트(OpenClaw, Claude Code, Codex 등)가 구현할 수 있으며, 에이전트가 관련성, 최신성, 중요도에 따라 결정론적으로 사실을 회상할 수 있게 합니다.
핵심 기능
- 기억 레이어: Markdown 파일 1개 = 기억 레코드 1개(사실, 엔티티, 에피소드, 절차). 기록할 때마다 Git 커밋이 생성되므로 롤백, 차이점 비교, 변경 사항 감사가 가능합니다.
- 프로토콜: AMP는 이식 가능한 JSON 매니페스트(
amp.json)와 고정된 디스크 레이아웃(memory/…)을 정의합니다. 호스트는 6개의 MCP 도구(memory_recall,memory_index등) 또는 CLI를 통해 상호작용합니다. - 결정론적 회상: 임베딩(embeddings)이나 외부 API 호출이 필요 없습니다. 회상 점수는 '관련성 × 최신성 감쇠 × 중요도'를 기반으로 로컬에서 계산됩니다.
- 출처 강제: 사용자(소유자) 또는 에이전트 자체가 생성한 콘텐츠만 저장할 수 있습니다. 신뢰할 수 없는 소스는 설계상 거부됩니다.
- 플러그인 우선: OpenClaw, Claude Code, Codex용 어댑터와 범용 파일 규칙 폴백을 제공하여 동일한 기억 저장소를 플랫폼 간에 공유할 수 있습니다.
- 링크 그래프: 레코드는
[[id]]링크로 서로 참조할 수 있어 그래프 탐색이 가능하며, 프롬프트에 주입할 수 있는 간결한 인덱스를 생성합니다.
대상 사용자
- AI 어시스턴트 개발자: 모든 에이전트 프레임워크에서 작동하는 감사 가능하고 오프라인 우선인 기억 저장소를 찾는 분.
- 데이터 출처를 중시하는 팀: 신뢰할 수 없는 쓰기 작업을 차단하는 내장 게이트가 필요한 팀.
- 오픈소스 AI 플랫폼 관리자(OpenClaw, Claude Code 등): 벡터 데이터베이스에 종속되지 않는 공통 기억 백엔드를 찾는 분.
- 연구원: 결정론적 회상 전략을 실험하거나 버전 관리된 기억이 에이전트 행동에 미치는 영향을 연구하는 분.
작동 방식(개요)
- 저장소 초기화 –
talewell init ./my-memory로amp.json과memory/트리를 포함한 디렉토리를 생성합니다. - 레코드 추가 –
talewell remember --text "Leo 不吃辣" --alias "饮食,辣,diet" --importance 7로 Markdown 파일(f-*.md)을 작성하고 커밋합니다. - 회상 –
talewell recall "订餐厅要注意什么"로 저장소를 스캔하고 각 사실의 점수를 매겨 최적의 결과를 반환합니다(전 과정 오프라인). - 수정 / 망각 –
correct로 사실을 대체(기록 유지)하거나forget으로 제거(감사를 위해 Git에는 남음)합니다. - 그래프 및 인덱스 –
talewell graph <id>로[[link]]참조를 추적하고,talewell index --markdown으로 에이전트 프롬프트에 주입 가능한 간결한 카탈로그를 생성합니다. - MCP를 통한 서비스 –
talewell serve-mcp로 6개의 기억 도구를 노출하는 서버를 실행하여 MCP 호환 호스트에서 호출할 수 있게 합니다. - 호스트 간 전송 –
talewell bundle ./transfer.bundle로 저장소를 패키징하여 플랫폼 간에 이동합니다.
미해결 과제 / 질문
- 임베딩 레이어: 핵심 설계는 의도적으로 벡터 검색을 배제합니다. 임베딩 추가는 선택 사항이며 기본 기능에 포함되지 않습니다.
- 확장성: Git은 중간 규모의 코퍼스에는 적합하지만, 매우 큰 기억 저장소에서는 성능 한계에 도달할 수 있습니다.
- 호스트 생태계: '검증됨'으로 나열된 호스트는 소수입니다. 나머지는 안전한 기본 설정에 의존합니다.
- 보안 모델: 출처 강제로 신뢰할 수 없는 쓰기는 차단되지만, README에는 MCP 서버 인증에 대한 세부 정보가 없습니다.
빠른 시작 (CLI)
# 1. 기억 저장소 생성
talewell init ./talewell-repo
# 2. 사실 기억하기
talewell remember \
--text "Leo 不吃辣" \
--alias "饮食,辣,diet" \
--importance 7
# 3. 회상하기
talewell recall "订餐厅要注意什么"
# 4. 호스트용 서비스 실행 (예: OpenClaw)
talewell serve-mcp
라이선스
MIT – 자유롭게 사용, 수정 및 재배포가 가능합니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트