FAVA Trails

Federated Agents Versioned Audit Trail — Git-native, curated memory for AI agents via MCP.

Every thought, decision, and observation is stored as a markdown file with YAML frontmatter in a Git repo you control, with crash-proof persistence and a versioned audit trail. Agents interact through MCP tools — they never see VCS commands.

Why

Supersession tracking — when an agent corrects a belief, the old version is hidden from default recall. No contradictory memories.
Draft isolation — working thoughts stay in drafts/. Other agents only see promoted thoughts.
Trust Gate — an LLM-based reviewer validates thoughts before they enter shared truth. Hallucinations stay contained in draft.
Full lineage — every thought carries who wrote it, when, and why it changed.
Crash-proof — every write is an atomic commit. No unsaved work.
Engine/Fuel split — this repo is the engine (stateless MCP server). Your data lives in a separate repo you control.

Install

Prerequisites

FAVA Trails uses Jujutsu (JJ) as its storage engine, running in colocate mode alongside Git. Your repo remains a standard Git repo (GitHub and CI/CD see normal commits; pushes go through the sync MCP tool or jj git push). One-time install:

fava-trails install-jj

From PyPI (recommended)

pip install fava-trails

From source (for development)

git clone https://github.com/MachineWisdomAI/fava-trails.git
cd fava-trails
uv sync

Quick Start

Set up your data repo

New data repo (from scratch):

# Create an empty repo on GitHub (or any git remote), then clone it
git clone https://github.com/YOUR-ORG/fava-trails-data.git

# Bootstrap it (creates config, .gitignore, initializes JJ in colocate mode)
fava-trails bootstrap fava-trails-data

Existing data repo (clone from remote):

fava-trails clone https://github.com/YOUR-ORG/fava-trails-data.git fava-trails-data

Register the MCP server

Add to your MCP client config:

Claude Code CLI: ~/.claude.json (top-level mcpServers key)
Claude Desktop: claude_desktop_config.json

If installed from PyPI:

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

If installed from source:

{
  "mcpServers": {
    "fava-trails": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fava-trails", "fava-trails-server"],
      "env": {
        "FAVA_TRAILS_DATA_REPO": "/path/to/fava-trails-data",
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

For Claude Desktop on Windows (accessing WSL):

{
  "mcpServers": {
    "fava-trails": {
      "command": "wsl.exe",
      "args": [
        "-e", "bash", "-lc",
        "FAVA_TRAILS_DATA_REPO=/path/to/fava-trails-data OPENROUTER_API_KEY=sk-or-v1-... fava-trails-server"
      ]
    }
  }
}

OpenAI Codex CLI: ~/.codex/config.toml

[mcp_servers.fava-trails]
command = "fava-trails-server"

[mcp_servers.fava-trails.env]
FAVA_TRAILS_DATA_REPO = "/path/to/fava-trails-data"
OPENROUTER_API_KEY = "sk-or-v1-..."

Other MCP clients (Crush, OpenCode, etc.): check your client's MCP config docs — most accept this JSON format:

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

The Trust Gate uses LLM verification: Thoughts are reviewed before promotion to ensure they're coherent and safe. By default, FAVA Trails uses OpenRouter to access 300–500+ models from 60+ providers including Anthropic, OpenAI, Google, Qwen, and others. Get a free API key at openrouter.ai/keys. The default model (google/gemini-2.5-flash) costs ~$0.001 per review. Multi-provider support via any-llm-sdk enables switching to other providers by modifying config.yaml.

Use it

Agents call MCP tools. Core workflow:

save_thought(trail_name="myorg/eng/my-project", content="My finding about X", source_type="observation")
  → creates a draft in drafts/

propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id)
  → promotes to observations/ (visible to all agents)

recall(trail_name="myorg/eng/my-project", query="X")
  → finds the promoted thought

Agents interact through MCP tools — they never see VCS commands.

Cross-Machine Sync

FAVA Trails uses git remotes for cross-machine sync. The fava-trails bootstrap command sets push_strategy: immediate which auto-pushes after every write.

Setting up a second machine

# 1. Install FAVA Trails
pip install fava-trails

# 2. Install JJ (storage engine; runs alongside Git in colocate mode)
fava-trails install-jj

# 3. Clone the SAME data repo (handles colocated mode + bookmark tracking)
fava-trails clone https://github.com/YOUR-ORG/fava-trails-data.git fava-trails-data

# 4. Register MCP (same config as above, with local paths)

Both machines push/pull through the same git remote. Use the sync MCP tool to pull latest thoughts from other machines.

Manual push (if auto-push is off)

Note: Most users never need these commands. The sync MCP tool and push_strategy: immediate handle everything automatically. These are for advanced manual intervention only.

cd /path/to/fava-trails-data
jj bookmark set main -r @-
jj git push --bookmark main

NEVER use git push origin main after JJ colocates — it misses thought commits. See AGENTS_SETUP_INSTRUCTIONS.md for the correct protocol.

Architecture

fava-trails (this repo)        fava-trails-data (your repo)
├── src/fava_trails/           ├── config.yaml
│   ├── server.py  ←── MCP ──→├── .gitignore
│   ├── cli.py                 └── trails/
│   ├── trail.py                   └── myorg/eng/project/
│   ├── config.py                      └── thoughts/
│   ├── trust_gate.py                      ├── drafts/
│   ├── hook_manifest.py                   ├── decisions/
│   ├── protocols/                         ├── observations/
│   │   └── secom/                         └── preferences/
│   └── vcs/
│       └── jj_backend.py
└── tests/

Engine (fava-trails) — stateless MCP server, Apache-2.0. Install via pip install fava-trails.
Fuel (fava-trails-data) — your organization's trail data, private.

Configuration

Environment variables:

Variable	Read by	Purpose	Default
`FAVA_TRAILS_DATA_REPO`	Server	Root directory for trail data (monorepo root)	`~/.fava-trails`
`FAVA_TRAILS_DIR`	Server	Override trails directory location (absolute path)	`$FAVA_TRAILS_DATA_REPO/trails`
`FAVA_TRAILS_SCOPE_HINT`	Server	Broad scope hint baked into tool descriptions	(none)
`FAVA_TRAILS_SCOPE`	Agent	Project-specific scope from `.env` file	(none)
`OPENROUTER_API_KEY`	Server	API key for Trust Gate LLM reviews via OpenRouter	(none — required for `propose_truth`)

LLM Provider: FAVA Trails uses any-llm-sdk for unified LLM access. OpenRouter is the default provider (recommended for simplicity — single API key, 300–500+ models from 60+ providers). Additional providers (Anthropic, OpenAI, Bedrock, etc.) can be configured in config.yaml for future versions.

The server reads $FAVA_TRAILS_DATA_REPO/config.yaml for global settings. Minimal config.yaml:

trails_dir: trails          # relative to FAVA_TRAILS_DATA_REPO
remote_url: null            # git remote URL (optional)
push_strategy: manual       # manual | immediate

When push_strategy: immediate, the server auto-pushes after every successful write. Push failures are non-fatal.

See AGENTS_SETUP_INSTRUCTIONS.md for full config reference including trust gate and per-trail overrides.

Protocols

FAVA Trails supports optional lifecycle protocols — hook modules that run custom logic at key points in the thought lifecycle (save, promote, recall). Protocols are registered in your data repo's config.yaml and loaded at server startup.

SECOM — Compression at Promote Time

Extractive token-level compression via LLMLingua-2, based on the SECOM paper (Tsinghua University and Microsoft, ICLR 2025). Thoughts are compressed once at promote time (WORM pattern), reducing storage and boosting recall density. Purely extractive — only original tokens survive, no paraphrasing or rewriting.

pip install fava-trails[secom]

Add to your data repo's config.yaml:

hooks:
  - module: fava_trails.protocols.secom
    points: [before_propose, before_save, on_recall]
    order: 20
    fail_mode: open
    config:
      compression_threshold_chars: 500
      target_compress_rate: 0.6
      compression_engine:
        type: llmlingua

Structured data: SECOM's token-level compression has no notion of syntactic validity — JSON objects, YAML blocks, and fenced code blocks may be silently destroyed at promote time. Tag thoughts with secom-skip to opt out:

save_thought(trail_name="my/scope", content='{"phases": [...]}', metadata={"tags": ["secom-skip"]})

The before_save hook warns when structured content is detected without secom-skip.

See protocols/secom/README.md for full config reference, model options, and the secom-skip opt-out. See AGENTS_SETUP_INSTRUCTIONS.md for the general hooks system.

Quick setup via CLI:

# Print default config (copy-paste into config.yaml)
fava-trails secom setup

# Write config directly + commit with jj
fava-trails secom setup --write

# Pre-download model to avoid first-use delay
fava-trails secom warmup

ACE — Agentic Context Engineering

Playbook-driven reranking and anti-pattern detection, based on ACE (arXiv:2510.04618) (Stanford, UC Berkeley, and SambaNova, ICLR 2026). Applies multiplicative scoring using rules stored in the preferences/ namespace.

pip install fava-trails  # included in base install

Add to your data repo's config.yaml:

hooks:
  - module: fava_trails.protocols.ace
    points: [on_startup, on_recall, before_save, after_save, after_propose, after_supersede]
    order: 10
    fail_mode: open
    config:
      playbook_namespace: preferences
      telemetry_max_per_scope: 10000

Quick setup via CLI:

fava-trails ace setup           # print default config
fava-trails ace setup --write   # write + jj commit

RLM — MapReduce Orchestration

Lifecycle hooks for MIT RLM (arXiv:2512.24601) MapReduce workflows. Validates mapper outputs, tracks batch progress, and sorts results deterministically for reducer consumption.

pip install fava-trails  # included in base install

Add to your data repo's config.yaml:

hooks:
  - module: fava_trails.protocols.rlm
    points: [before_save, after_save, on_recall]
    order: 15
    fail_mode: closed
    config:
      expected_mappers: 5
      min_mapper_output_chars: 20

Quick setup via CLI:

fava-trails rlm setup           # print default config
fava-trails rlm setup --write   # write + jj commit

Development

uv run pytest -v          # run tests
uv run pytest --cov       # with coverage

Docs

AGENTS.md — Agent-facing: MCP tools reference, scope discovery, thought lifecycle, agent conventions
AGENTS_USAGE_INSTRUCTIONS.md — Canonical usage: scope discovery, session protocol, agent identity
AGENTS_SETUP_INSTRUCTIONS.md — Data repo setup, config reference, trust gate prompts, lifecycle hooks
protocols/secom/README.md — SECOM compression protocol: config, models, WORM architecture
docs/fava_trails_faq.md — Detailed FAQ for framework authors and ML engineers

Contributing

See CONTRIBUTING.md for setup instructions, how to run tests, and PR expectations.

See CHANGELOG.md for release history.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FAVA Trails

Why

Install

Prerequisites

From PyPI (recommended)

From source (for development)

Quick Start

Set up your data repo

Register the MCP server

Use it

Cross-Machine Sync

Setting up a second machine

Manual push (if auto-push is off)

Architecture

Configuration

Protocols

SECOM — Compression at Promote Time

ACE — Agentic Context Engineering

RLM — MapReduce Orchestration

Development

Docs

Contributing

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

FAVA Trails

Why

Install

Prerequisites

From PyPI (recommended)

From source (for development)

Quick Start

Set up your data repo

Register the MCP server

Use it

Cross-Machine Sync

Setting up a second machine

Manual push (if auto-push is off)

Architecture

Configuration

Protocols

SECOM — Compression at Promote Time

ACE — Agentic Context Engineering

RLM — MapReduce Orchestration

Development

Docs

Contributing