Install

pip install fava-trails

"fava-trails": {
  "command": "fava-trails-server",
  "env": {
    "FAVA_TRAILS_DATA_REPO": "/path/to/fava-trails-data",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}

누구에게 맞나

FAVA Trails(Federated Agents Versioned Audit Trail)는 MCP를 통해 AI 에이전트에 노출되는 Git 네이티브 메모리 시스템입니다. 에이전트가 만들어낸 생각, 판단, 관찰은 YAML frontmatter가 붙은 Markdown 파일로, 사용자 자신이 통제하는 Git 데이터 저장소에 기록됩니다. 타인의 서버에 맡겨진 블랙박스가 아니라는 뜻입니다. '초안'과 '모든 에이전트에게 보이는 관찰'을 두 단계로 나누고 그 사이에 승격 게이트를 두었으며, 에이전트는 평소 메모리 도구만 다루고 버전 관리 명령에는 직접 닿지 않습니다. 버전 관리 세부 사항은 엔진이 저장소 안에서 처리하고, 전체 이력은 커밋 기록에 남아 언제든 되돌아 볼 수 있습니다.

맞는 경우: 여러 에이전트가 작업 메모리를 공유하고 쌓아가려는 팀이나 개인. 예를 들어 엔지니어링 조사 결론이나 세션을 가로지르는 의사결정 맥락을 재사용 가능한 관찰로 저장하려는 경우. 메모리가 버전 관리되고 추적 가능하며 언제든 파일로 직접 확인되기를 바라는 사용자. 이미 Git으로 자산을 관리하고 있어 데이터 저장소를 하나 더 유지해도 괜찮은 사람.
사용 전제: 로컬에서 pip로 설치가 가능할 것. 설정에서 데이터 저장소 경로를 FAVA_TRAILS_DATA_REPO로 지정할 것. 초안을 모든 에이전트에게 보이는 관찰로 승격하려면 OpenRouter API key를 반드시 설정해야 합니다.
신중하게: 데이터 저장소를 유지하고 싶지 않거나 OpenRouter key를 발급받고 싶지 않은 사용자는 신중해야 합니다. 에이전트 간 메모리 공유라는 핵심 경로가 이 둘에 동시에 의존하기 때문입니다.
알 수 없는 부분: 증거는 지원되는 구체적인 MCP 클라이언트, OS와 Python 버전 요구 사항, 저장 엔진 Jujutsu(JJ)를 별도로 설치해야 하는지를 말해 주지 않습니다.

3분 만에 첫 시도

권장 주 경로는 하나뿐입니다. PyPI에서 엔진을 설치한 뒤 MCP 클라이언트의 서버 설정에 등록하면 됩니다. 전제는 두 가지입니다. 데이터 저장소로 쓸 위치를 먼저 정할 것(설정의 FAVA_TRAILS_DATA_REPO가 그곳을 가리킵니다), 그리고 승격 단계까지 가려면 OpenRouter API key가 필요하다는 점입니다.

첫 번째, Apache-2.0 라이선스의 스테이트리스 MCP 서버를 설치합니다:

pip install fava-trails

두 번째, 공식 등록 스니펫을 클라이언트 설정에 추가하고 저장소 경로를 실제 위치로 바꿉니다:

"fava-trails": {
  "command": "fava-trails-server",
  "env": {
    "FAVA_TRAILS_DATA_REPO": "/path/to/fava-trails-data",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}

세 번째, 에이전트가 범위가 가장 작은 쓰기를 한 번 호출하게 합니다. save_thought로 관찰 하나를 초안으로 기록하는 것입니다.

save_thought(trail_name="myorg/eng/my-project", content="My finding about X", source_type="observation")

성공 신호: 데이터 저장소의 drafts/ 디렉터리에 이 초안이 나타납니다. 작업의 성격은 분명히 해 두세요. 이 단계는 로컬 쓰기로, 파일이 자신의 저장소에 떨어지는 것이지 읽기 전용 조회가 아닙니다. 초안을 삭제하거나 되돌리는 방법은 공식적으로 제공되지 않으므로 첫 시도에는 무해한 내용을 쓰세요. 엔진 쪽에서는 Jujutsu(JJ)가 저장 엔진으로 Git과 함께 colocate 모드로 병행되고, 저장소는 여전히 표준 Git 저장소이므로 이 단계에서 버전 관리 명령을 만질 필요가 없습니다. 또한 OpenRouter API key의 경계에도 주의하세요. 이 공식 설정 템플릿에 이미 등장하고, 공식 표는 propose_truth에 필수이며 Trust Gate의 LLM 검토를 OpenRouter를 통해 수행한다고 덧붙입니다. 첫 시도는 초안 단계에서 멈추면 되고, 곁들여 승격할 필요는 없습니다.

사용 사례

사례 1: 조사 결론을 프로젝트 메모리로 쌓기. 시나리오: 에이전트가 막 조사를 마쳤고 결론이 이후 세션에서 재사용할 가치가 있는 경우. 방법: save_thought를 trail_name, content, source_type 인자로 호출합니다. 위의 공식 예시 호출을 그대로 쓸 수 있습니다. 기대 결과: drafts/ 디렉터리에 초안 파일이 생기고, 내용은 자신의 저장소에만 남으며 다른 에이전트는 아직 볼 수 없어 누구에게도 영향을 주지 않습니다. 초안은 일반 파일이라 저장소에서 바로 열어 확인할 수 있습니다.

사례 2: 확인된 초안을 공유 관찰로 승격하고 검색으로 검증하기. 시나리오: 어떤 관찰이 검증되었고 이후 모든 에이전트가 찾을 수 있게 하려는 경우. 방법: 먼저 OpenRouter API key가 유효한지 확인하고, propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id)로 초안을 observations/로 승격한 뒤 recall(trail_name="myorg/eng/my-project", query="X")로 검색합니다. 기대 결과: recall이 승격된 생각을 찾고, 같은 데이터 저장소에 연결된 다른 에이전트도 같은 질의로 찾을 수 있습니다. 확인 포인트: 승격 결과는 모든 에이전트에게 보이고 공식적으로 되돌리는 방법이 없으므로, 실행 전에 내용이 공유에 적합한지 확인하세요. 변경을 원격으로 push하는 것은 별도의 독립 동작으로, sync 도구나 jj git push를 다시 호출해야 합니다.

사용 경계

읽기/쓰기 성격: save_thought는 데이터 저장소에 초안을 만들고, propose_truth는 초안을 모든 에이전트에게 보이는 observations/로 승격합니다. 둘 다 쓰기이며, recall은 승격된 생각을 찾습니다. 쓰기는 자신의 저장소 안에서 일어나고 승격 자체는 먼저 로컬에 반영됩니다. 원격으로의 push는 sync MCP 도구나 jj git push로 별도로 수행해야 하며, 동기화 여부는 사용자가 정합니다. 공식적인 되돌리기·삭제 경로가 없으므로 쓰기를 언제든 되돌릴 수 있는 작업으로 보지 마세요.
자격 증명과 설정: FAVA_TRAILS_DATA_REPO가 데이터 저장소 위치를 지정하고 OPENROUTER_API_KEY는 승격 시 LLM 검토에 쓰입니다. 둘 다 공식 설정 템플릿의 env 섹션에 들어가며, 공식 문서는 후자가 propose_truth에 필수라고 명시합니다. 이 key가 없을 때 save_thought와 recall이 동작하는지는 증거에 언급이 없습니다.
실행 환경과 데이터 보관: 저장 엔진은 Jujutsu(JJ)로 Git과 colocate 모드로 병행되며, 저장소는 여전히 표준 Git 저장소이고 GitHub과 CI/CD는 정상 커밋을 봅니다. 모든 내용은 YAML frontmatter가 붙은 Markdown 파일로 사용자가 통제하는 저장소에 보관됩니다.
미확인 항목: 용량 쿼터, 다중 저장소 규모 한도, 프라이버시와 데이터 저장 지역 세부 사항은 증거에 없습니다. Trust Gate 검토의 판정 기준과 실패 시 처리 방식도 설명되어 있지 않고, jj를 직접 설치해야 하는지, 지원 클라이언트와 Python 버전도 미확인입니다. '설명이 보이지 않는다'를 '위험이 없다'로 받아들이지 말고, 쓰는 내용은 '내 저장소에 오래 남을 것'으로 평가하세요.

AI 기능 카테고리

FAVA Trails: AI 에이전트를 위한 Git 네이티브 공유 메모리(MCP)

Install

누구에게 맞나

3분 만에 첫 시도

사용 사례

사용 경계