fava-trails

FAVA Trails is a stateless MCP server that stores thoughts, observations, and decisions as markdown files in a version-controlled data repository. It provides MCP tools that agents use to create, promote, and query memories without exposing underlying VCS operations. The server relies on a separate data repo (configured via FAVA_TRAILS_DATA_REPO) where drafts, observations, and drafts are kept, and it can automatically push changes depending on your push_strategy. Typical workflows include saving a thought as a draft, promoting it to truth, and then recalling promoted thoughts based on a query.

To use it, install FAVA Trails from PyPI and run the MCP server. You can configure the MCP client with the fava-trails server details, including the data repo path and an OpenRouter API key if you plan to use the Trust Gate for reviews. Core MCP tool calls you’ll interact with are save_thought (to draft a new idea), propose_truth (to promote a draft to an observable truth), and recall (to search for promoted thoughts). These tools are designed to be used by agents through your MCP client configuration rather than by direct VCS commands, ensuring a clean separation between reasoning and data storage.

Prerequisites:

• Python (3.8+ recommended)
• Pip (comes with Python)
• Jujutsu (JJ) installed if you intend to bootstrap or manage JJ-backed repos (as described by FAVA Trails)
• Optional: access to an OpenRouter API key if you plan to use Trust Gate reviews

From PyPI (recommended):

pip install fava-trails

Run the MCP server (example for PyPI install):

# Start the MCP server (the binary is exposed as fava-trails-server when installed from PyPI)
fava-trails-server

If you are developing from source and want to run the server via uv (required for development):

uv run fava_trails/server.py

Register or configure your MCP client with the server, pointing to the data repo for FAVA Trails data:

{
  "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-..."
      }
    }
  }
}

Bootstrap a data repo and set up JJ as described in the README to get started with a working environment.

Tips and common issues:

• Ensure FAVA_TRAILS_DATA_REPO points to a writable directory containing your data repository for trails.
• If you enable push_strategy: immediate, server-side writes will auto-push after every write; handle push failures gracefully.
• For Trust Gate usage, you need an OPENROUTER_API_KEY; without it, propose_truth will not be able to route reviews.
• When running from source, you may use uv commands to execute the server script directly; from PyPI, fava-trails-server is the entry point.
• The server is designed to be data-store agnostic and relies on your JJ-backed data repo for history and provenance.
• Refer to AGENTS_SETUP_INSTRUCTIONS.md and AGENTS.md for detailed tool references, scope handling, and lifecycle rules.