FAVA Trails · Open-source agent memory

Agent memory should be curated, not just accumulated.

FAVA Trails is open-source agent memory by Machine Wisdom AI. Agents share reviewed decisions across sessions and environments, with drafts kept separate from approved records and corrections preserved in version history. Connect through MCP and keep your Markdown records in a Git repository you control.

pip install fava-trails

Get started on GitHub View on PyPI

Federated Agents Versioned Audit Trail

Built with Git-Native Model Context Protocol Python

When a working assumption becomes shared memory

An agent can mistake a temporary failure for a lasting constraint. If that observation enters shared memory without review, another agent can reuse it long after the original context has disappeared. The engineering question is who can publish a memory, what review it receives, and how a correction reaches later readers.

Machine Wisdom AI built FAVA Trails around that question. A draft has an author, promotion records a review, and an approved correction replaces the earlier record while preserving its history. Our two-agent case study follows a stale reference through that correction process.

How It Works

FAVA Trails separates saving a thought from accepting it into shared memory. The review and revision history stays with the record as agents work across environments.

Draft Isolation

save_thought(trail_name="team/project", content="Cache test needs a repeat run.")

before_save after_save

A saved thought starts as a draft. Default recall returns approved current records; an agent reads its own drafts through explicit authoring mode. Configure a separate process identity for each authoring agent.

Promotion Gate

propose_truth(trail_name="team/project", thought_id="<saved-id>")

before_propose after_propose

The Trust Gate reviews the candidate against a rubric before promotion. It can use a local or hosted model. A failed or unavailable review does not approve the record. Review is a quality control step, not independent verification that the claim is true.

See how a local model performs as the gate →

Shared Truth

sync(trail_name="team/project")

After approved records are published to the shared data remote, other environments fetch them with sync(). Sync fetches and rebases; it does not push. Approved corrections make older records historical, so default recall returns the current approved version.

What Makes Agent Memory Durable

Each record retains its author, review state, and revision history, giving agents and operators a way to distinguish an accepted decision from work still in progress.

Supersession Chains

A correction starts as a draft successor. Once approved, it becomes the current record and links back to its predecessor. Agents can retrieve the accepted version while an operator can inspect how the decision changed.

Versioned Persistence

Successful saves persist Markdown records through Jujutsu and Git, preserving completed work across sessions. Interrupted operations can need recovery; the repository keeps the history available for inspection.

Federated Coordination

Agents in different environments share a versioned data repository. Conflicting changes are surfaced for resolution instead of silently overwriting one another.

MCP + CLI

MCP tools let compatible agents save, review, and recall records. The CLI handles setup, diagnostics, and reading. The server and your memory repository remain separate, so you control the durable data.

Lifecycle Hooks

Plug research-backed intelligence into the memory pipeline. Each hook intercepts a lifecycle moment — each protocol is a pre-built implementation you enable with one command.

save_thought() → before_save → persist → after_save

propose_truth() → before_propose → review → after_propose

recall() → → retrieve → on_recall

startup → → init → on_startup

SECOM

Extractive Compression

Compresses thoughts at promote time via token-level extraction. Keeps the semantic core, drops the noise.

before_propose

fava-trails secom setup --write

Tsinghua / Microsoft — ICLR 2025

ACE

Playbook Reranking

Reranks recalled thoughts against your playbook rules. Detects stale references, contradictions, and unsupported claims.

on_recall on_startup

fava-trails ace setup --write

Stanford / UC Berkeley / SambaNova

RLM

MapReduce Orchestration

Validates mapper outputs, tracks batch progress, and sorts results for reducer consumption.

before_save on_recall

fava-trails rlm setup --write

MIT

Explore All Protocols

From manual handoffs to reviewed records

An illustrative workflow comparison with manually relaying agent context.

Operation	Manual handoff	With FAVA Trails
Share research	Operator copies between agents manually	Agent saves and promotes a record. Other agents recall it after publication and sync.
Correct a stale reference	Operator relays error. Source agent regenerates entire document	An approved successor replaces the stale record and preserves its lineage.
Review candidate memories	Every write immediately visible. Contamination spreads silently	Writes enter as drafts. Promotion requires `propose_truth()`
Audit what changed	Operator's memory. Chat logs across conversations	Supersession chain: parent_id, agent_id, timestamps
Roll back a mistake	Manual cleanup. Hope you found all contaminated entries	`rollback()` restores a prior repository operation; review its repository-wide scope first.
Resume in new session	Operator re-briefs from scratch	`recall()` searches approved current decisions by matching query terms.

See how FAVA Trails compares to vector databases, knowledge graphs, and structured task trackers in our landscape analysis.

Who Is This For

Running Multiple Agents?

Read the case study

When agents share decisions, a mistaken assumption can travel between them. FAVA Trails separates drafts from approved records and preserves correction history, so teams can review what becomes shared memory.

Long-Running Sessions?

See how it works

Keep accepted decisions beyond a single session. FAVA Trails persists saved records and supports lexical recall, letting an agent retrieve relevant approved context when it resumes work.

Governing Context That Won't Fit?

Explore protocols

A 1,000-page spec, a regulatory corpus, a sprawling style guide. When the governing context exceeds a single context window, lifecycle hooks and context engineering protocols handle the splitting, compression, and reassembly. Built-in protocols include ACE (Stanford, UC Berkeley, SambaNova), SECOM (Tsinghua, Microsoft), and RLM (MIT). Or write your own.

Quick Start

Start with a local repository, then connect your MCP agent. The current governed recall model ships in FAVA Trails 0.7.0 and later.

For shared publishing, identity boundaries, and recovery, follow the FAVA Trails README. A local repository works without a remote; synchronization needs a configured shared remote.

Install

pip install --upgrade fava-trails
fava-trails version
fava-trails install-jj   # one-time storage engine setup

The storage engine is Jujutsu (JJ), running in colocate mode alongside Git. One-time install; your repo remains a standard Git repo. This does not replace Git.

Set Up a Data Repo

Your data lives in a separate repository you control. Start locally, or clone a shared data repository your team already operates:

# Local evaluation
fava-trails bootstrap fava-trails-data

# Or clone an existing one
fava-trails clone https://github.com/YOUR-ORG/fava-trails-data.git fava-trails-data

Register as an MCP Server

Add to your MCP client config (~/.claude.json for Claude Code CLI, claude_desktop_config.json for Claude Desktop):

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

Give each authoring process its own FAVA_TRAILS_AGENT_ID and restart the MCP client after changing its configuration. The Trust Gate reviews drafts before promotion. We recommend serving it from a local OpenAI-compatible endpoint such as Unsloth Studio or vLLM, configured in ~/.config/fava-trails/config.yaml, to keep review requests on that machine. In our benchmark, a quantized Qwen 3.6 model proved on par with Gemini for this job →

Hosted review through OpenRouter is another supported option: supply your own API key from openrouter.ai/keys. With a local gate, the OPENROUTER_API_KEY entry is not needed.

Optional: Enable Lifecycle Protocols

# Pick any combination — each is independent
fava-trails secom setup --write   # compression (requires [secom] extra)
fava-trails ace setup --write     # playbook reranking
fava-trails rlm setup --write     # MapReduce orchestration

Each protocol hooks into the memory lifecycle and enables independently. SECOM compresses, ACE reranks, RLM orchestrates — pick the ones that fit your workflow. Explore protocols →

How two agents corrected a shared decision

A Claude Desktop agent and a Claude Code CLI agent collaborated on a spec through shared curated memory. When one agent found stale references, it superseded a single thought. The operator prompted the other agent to check the trail, and it read the correction without the operator relaying the corrected content.

Read the Full Case Study

Built by Machine Wisdom AI

The engineering behind shared agent memory

FAVA Trails makes a specific architecture choice: saving an observation and accepting it as shared knowledge are separate operations. That choice gives teams a place to review a claim, record a correction, and inspect the decisions an agent relied on.

Machine Wisdom AI publishes the implementation and the reasoning behind it. Explore the architecture, examine a worked example, and use the source to evaluate the design for your own agents.

Read Machine Wisdom AI’s writing on production AI

Try FAVA Trails

Curated agent memory with the process discipline of production codebases.

Apache 2.0 licensed. Git-native. Your data stays in a repo you control.

$ pip install fava-trails

Get started on GitHub

Built by Machine Wisdom AI. Explore hands-on help with agent architecture, evaluation, and production delivery.