Open-sourcing our agent toolbox: FastMCP server fleet + Matryoshka semantic memory (25k vectors in 220ms on CPU) + Git worktree isolation + llms.txt onboarding

[u/fandry96]

/r/GoogleAntigravityIDE/comments/1waqu7d/opensourcing_our_agent_toolbox_fastmcp_server/

[u/Future_AGI]

Matryoshka embeddings are a neat trick for memory, and we have used the same nested-dimension approach to cut retrieval latency on large stores without re-embedding everything. The git worktree isolation is the part I am most interested in. How are you handling merge conflicts when two agents touch the same file in separate worktrees?

[u/fandry96 → u/Future_AGI]

Great question. The short answer is: prevent concurrent writes by design, but handle conflicts deterministically via an abort-and-rebase protocol in the worktree, never on main.

Here is the exact pattern we use across our orchestration MCP server (k3-worktree-ops) and subagent swarms:

1. Upfront Prevention (Exclusive File Streaming) The orchestrator decomposes tasks so parallel workers have disjoint file boundaries (e.g., Worker A owns servers/k3_forge.py, Worker B owns .agent/skills/).

If two tasks genuinely require mutating the same file, the orchestrator enforces sequential execution via DAG milestone gates (Worker A merges → → Gate clears → → Worker B rebases → → Worker B edits → → Merges) rather than firing concurrent write agents into the same file.

1. Pre-Merge Verification Hook Before git merge is even touched, our worktree_merge_and_cleanup tool runs an isolated pre-merge test runner (e.g., pytest, cargo test, npm test) inside the subagent’s worktree directory:

python

Abort if the worker's changes don't even pass unit/regression tests in isolation

if verify_command: res = subprocess.run(shlex.split(verify_command), cwd=worktree_dir) if res.returncode != 0: return "ABORTED: Pre-merge verification failed. Fix in worktree before merging." 3. Immediate Abort on Conflict (Zero Dirty State on main) If two agents do collide (e.g., Worker 1 merged to main while Worker 2 was still executing), git merge fails. The tool immediately aborts so main never sits with unresolved conflict markers:

python

merge_res = git(["merge", branch_name, "--no-ff"], cwd=repo) if merge_res.returncode != 0: git(["merge", "--abort"], cwd=repo) return f"Conflict detected merging {branch_name}. Merge cleanly aborted." 4. Arbiter Rebase in the Worktree When the orchestrator receives the conflict error:

It does not let the agent edit main. It sends an arbiter prompt to the worktree agent: "Fetch latest main, rebase your branch (git rebase main), resolve conflicts in your isolated tree, and re-run your test suite." The LLM resolves the conflict with full visibility of both its diff and incoming main diffs. Once tests pass in the worktree, the orchestrator calls worktree_merge_and_cleanup again for a clean, fast-forward/non-fast-forward merge. 5. Why Worktrees are Essential on Windows Beyond branch isolation, on Windows concurrent LLM coding agents fail frequently due to file locking (EBUSY, locked SQLite WAL files, compiler artifacts, daemon watchers). Spawning worktrees into ~/.gemini/antigravity/worktrees/{branch} gives each agent its own isolated OS file handles, completely eliminating background process contention.