From e9649a12978aa1a4f4f885061aa5fd887a03086f Mon Sep 17 00:00:00 2001 From: "Younes (Machine Wisdom)" Date: Fri, 3 Apr 2026 08:33:37 -0400 Subject: [PATCH 1/2] docs: reframe JJ as implementation detail in README, lead with Git-native outcomes Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a1928cc..724dbab 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ # FAVA Trails -**Federated Agents Versioned Audit Trail** — VCS-backed memory for AI agents via MCP. +**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, tracked in a [Jujutsu (JJ)](https://jj-vcs.github.io/jj/) colocated git monorepo. Agents interact through [MCP](https://modelcontextprotocol.io/) tools — they never see VCS commands. +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 an immutable audit trail. Agents interact through [MCP](https://modelcontextprotocol.io/) tools — they never see VCS commands. ## Why @@ -16,21 +16,19 @@ Every thought, decision, and observation is stored as a markdown file with YAML - **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** — JJ auto-snapshots. No unsaved work. +- **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 -Install [Jujutsu (JJ)](https://jj-vcs.github.io/jj/) — FAVA Trails uses JJ as its VCS engine: +FAVA Trails uses [Jujutsu (JJ)](https://jj-vcs.github.io/jj/) as its storage engine, running in colocate mode alongside Git. Your repo remains a standard Git repo (push to GitHub, CI/CD sees normal commits). One-time install: ```bash fava-trails install-jj ``` -Or install manually from [jj-vcs.github.io/jj](https://jj-vcs.github.io/jj/). - ### From PyPI (recommended) ```bash @@ -55,7 +53,7 @@ uv sync # 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) +# Bootstrap it (creates config, .gitignore, initializes storage engine) fava-trails bootstrap fava-trails-data ``` @@ -166,7 +164,7 @@ recall(trail_name="myorg/eng/my-project", query="X") → finds the promoted thought ``` -Agents interact through MCP tools — they never see VCS commands. JJ expertise is not required. +Agents interact through MCP tools — they never see VCS commands. ## Cross-Machine Sync @@ -178,7 +176,7 @@ FAVA Trails uses git remotes for cross-machine sync. The `fava-trails bootstrap` # 1. Install FAVA Trails pip install fava-trails -# 2. Install JJ +# 2. Install the storage engine (runs alongside Git in colocate mode) fava-trails install-jj # 3. Clone the SAME data repo (handles colocated mode + bookmark tracking) @@ -191,6 +189,8 @@ Both machines push/pull through the same git remote. Use the `sync` MCP tool to ### 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. + ```bash cd /path/to/fava-trails-data jj bookmark set main -r @- From 1fd85509553c8b48180b4802da9158c32bdeb99b Mon Sep 17 00:00:00 2001 From: "Younes (Machine Wisdom)" Date: Fri, 3 Apr 2026 08:41:38 -0400 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20address=20code=20review=20=E2=80=94?= =?UTF-8?q?=20tighten=20audit=20trail=20claim,=20clarify=20push=20path,=20?= =?UTF-8?q?name=20JJ=20in=20comments?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 724dbab..89e13c5 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ **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 an immutable audit trail. Agents interact through [MCP](https://modelcontextprotocol.io/) tools — they never see VCS commands. +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](https://modelcontextprotocol.io/) tools — they never see VCS commands. ## Why @@ -23,7 +23,7 @@ Every thought, decision, and observation is stored as a markdown file with YAML ### Prerequisites -FAVA Trails uses [Jujutsu (JJ)](https://jj-vcs.github.io/jj/) as its storage engine, running in colocate mode alongside Git. Your repo remains a standard Git repo (push to GitHub, CI/CD sees normal commits). One-time install: +FAVA Trails uses [Jujutsu (JJ)](https://jj-vcs.github.io/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: ```bash fava-trails install-jj @@ -53,7 +53,7 @@ uv sync # 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 storage engine) +# Bootstrap it (creates config, .gitignore, initializes JJ in colocate mode) fava-trails bootstrap fava-trails-data ``` @@ -176,7 +176,7 @@ FAVA Trails uses git remotes for cross-machine sync. The `fava-trails bootstrap` # 1. Install FAVA Trails pip install fava-trails -# 2. Install the storage engine (runs alongside Git in colocate mode) +# 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)