FAVA Trails: Git-Native Shared Memory for AI Agents (MCP)

Who it's for

FAVA Trails (Federated Agents Versioned Audit Trail) is a Git-native memory system exposed to AI agents via MCP: the thoughts, decisions, and observations agents produce are written as Markdown files with YAML frontmatter into a Git data repository you control, not into a black box hosted on someone else's server. It splits "drafts" and "observations visible to all agents" into two tiers with a promotion gate in between; agents normally see only the memory tools themselves and never touch version control commands — versioning details are handled by the engine inside the repository, and the full history stays reviewable in the commit log.

• Good fit: teams or individuals who want multiple agents to share and accumulate working memory — for example, storing engineering troubleshooting conclusions or cross-session decision context as reusable observations; users who want memory that is versioned, traceable, and directly viewable as files at any time; people already managing assets with Git who don't mind maintaining one more data repository.
• Prerequisites: pip must be able to install on your machine; the configuration must provide the data repository path FAVA_TRAILS_DATA_REPO; to promote a draft into an observation visible to all agents, you must configure an OpenRouter API key.
• Weigh carefully: if you don't want to maintain a data repository or apply for an OpenRouter key, be cautious — the core cross-agent shared-memory path depends on both at once.
• Unknown: the evidence does not say which specific MCP clients are supported, what OS and Python version requirements exist, or whether the storage engine Jujutsu (JJ) needs to be installed separately.

First try in 3 minutes

There is only one recommended main path: install the engine from PyPI, then register it in your MCP client's server configuration. Two prerequisites: decide up front where the data repository will live, since FAVA_TRAILS_DATA_REPO in the configuration points to it; and to reach the promotion step, you need an OpenRouter API key.

Step one, install this Apache-2.0 licensed stateless MCP server:

pip install fava-trails

Step two, add the official registration snippet to your client configuration and replace the repository path in it with your actual location:

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

Step three, have the agent call the smallest-scope write once: use save_thought to record one observation as a draft.

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

Success signal: the draft appears under the drafts/ directory of the data repository. Be clear about the nature of the operation: this step is a local write that lands a file in your own repository, not a read-only query; there is no official documentation for deleting or undoing a draft, so write harmless content on the first try. On the engine side, Jujutsu (JJ) runs as the storage engine alongside Git in colocate mode; the repository remains a standard Git repository, and you do not touch any version control command at this step. Also note the boundary of the OpenRouter API key: it already appears in this official configuration template, and the official table further states that it is required for propose_truth, powering the Trust Gate's LLM reviews via OpenRouter; a first try can stop at the draft step — no need to promote along the way.

Use cases

Case one: turn the conclusion of an investigation into project memory. Scenario: an agent has just finished an investigation and the conclusion is worth reusing in later sessions. What to do: call save_thought with trail_name, content, and source_type — the official example call above works as-is. Expected result: a draft file appears in drafts/, the content lands only in your repository, other agents cannot see it yet and nobody is affected; the draft is a plain file you can open directly in the repository.

Case two: promote a verified draft to a shared observation, then verify it by retrieval. Scenario: an observation has been confirmed and you want every later agent to be able to find it. What to do: first confirm the OpenRouter API key is valid, call propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id) to promote the draft to observations/, then retrieve it with recall(trail_name="myorg/eng/my-project", query="X"). Expected result: recall finds the promoted thought, and other agents connected to the same data repository can find it with the same query. Checkpoint: the promotion result is visible to all agents and no official undo is documented, so confirm the content is fit for sharing before executing; pushing the change to a remote is a separate action that requires calling the sync tool or jj git push.

Where the limits are

• Read/write nature: save_thought creates a draft in the data repository and propose_truth promotes a draft to observations/ visible to all agents — both are writes; recall finds promoted thoughts. Writes happen inside your own repository, and a promotion lands locally first; pushing to a remote must be done separately via the sync MCP tool or jj git push, and whether to sync is your call. There is no official undo or delete path — do not treat a write as an operation you can roll back at any time.
• Credentials and configuration: FAVA_TRAILS_DATA_REPO specifies the data repository location and OPENROUTER_API_KEY powers the LLM review at promotion; both go in the env section of the official configuration template, and the official documentation explicitly says the latter is required for propose_truth. Whether save_thought and recall work without that key is not stated in the evidence.
• Runtime and data storage: the storage engine is Jujutsu (JJ) running alongside Git in colocate mode; the repository remains a standard Git repository, and GitHub and CI/CD see normal commits. All content is stored as Markdown files with YAML frontmatter in the repository you control.
• Unconfirmed items: capacity quotas, multi-repository scale limits, and privacy and data residency details are all absent from the evidence; the Trust Gate's review criteria and failure handling are likewise unstated, and so are whether jj must be installed separately and which clients and Python versions are supported. Do not read "no documentation seen" as "no risk" — evaluate what you write on the assumption that it will stay in your repository long-term.