Cross-agent shared vault: standalone implementation brief

cross-agent-vault-brief.md

Cross-agent vault: implementation brief

Source article: https://dev.to/arasovic/sharing-memory-between-three-ai-agents-claude-code-codex-and-hermes-394h

Turkish version: https://blog.arasmehmet.com/%C3%BC%C3%A7-ai-agent-tek-bellek-claude-code-codex-hermes-ve-syncthing-01aadebeb2fc

This brief is a standalone, copy-paste runbook for a filesystem-capable coding agent (Claude Code, Codex CLI, Hermes Agent, or similar). Copy this entire document into the agent's prompt; the agent sets up the cross-agent memory contract layer.

Prerequisite

This brief operates on top of an existing Syncthing setup. The agent does not install Syncthing or configure peers. If Syncthing is not already running and bidirectionally syncing a folder across two or more devices, set that up first; the official getting-started guide takes about fifteen minutes:

https://docs.syncthing.net/intro/getting-started.html

Assumptions

• You (the reader, instructing your agent) already have a local folder synced by Syncthing across two or more devices. Path to the folder is known.
• The agent can read and write files under that folder.
• The agent will not be asked to install Syncthing, set up peer pairing, or modify system services.
• The agent should not read .env, .pem, or any credential-shaped file in or near the vault.
• For *.sync-conflict-* files, the agent must not silently merge. Show the diff, wait for the user's explicit resolution decision, and execute it (delete the conflict, keep the conflict instead, or merge manually).

Task

Create a shared vault structure for cross-agent memory at the given Syncthing-backed folder path. Run this on a single peer; Syncthing will propagate the result to the others. Write the files listed below using the exact content shown, then run the verification commands at the end.

Files to create

• INDEX.md (hub file)
• personal/travel.md, projects/web-app.md, projects/mobile-app.md, ops/servers.md, notes/journal.md, reference/links.md (example spokes, skeletal templates)
• agent-config-snippet.md (block to be added to each agent's CLAUDE.md / AGENTS.md / SOUL.md)

Exact content

INDEX.md

# Vault: name

Cross-agent shared notes. Claude Code, Codex CLI, and Hermes Agent
all read from and update this directory.

## Workflow

- Session start: read this file.
- Read a linked detail file on-demand when more context is needed.
  Do not open files not referenced here.
- Updates: edit/append/toggle at line level. Do not rewrite whole files
  unless the user explicitly says "reset".
- Re-read the target file before writing (another agent may have edited it).

## Files

- [personal/travel.md](personal/travel.md): trip plans, dates, status
- [projects/web-app.md](projects/web-app.md): active web project
- [projects/mobile-app.md](projects/mobile-app.md): secondary project
- [ops/servers.md](ops/servers.md): utility VPS, home device, services
- [notes/journal.md](notes/journal.md): daily log
- [reference/links.md](reference/links.md): external resources

agent-config-snippet.md

This block goes into each agent's config file (CLAUDE.md for Claude Code, AGENTS.md for Codex, SOUL.md for Hermes Agent). Identical content across all three.

## Shared Vault

Vault path on this machine: <local-path>
(Syncthing bidirectional with two other peers, latency ~10 seconds.)

### Workflow

1. At session start, read <vault-path>/INDEX.md.
2. Read a linked file on-demand when detail is needed.
   Do not open files not referenced in INDEX.md.
3. When a state update happens (e.g., "passport arrived"), update
   the relevant linked file. Format:
   - State: `- [x] Passport: arrived (2026-05-14)`
   - Event log: `## YYYY-MM-DD HH:MM UTC` heading at file bottom.
4. Edit, append, or toggle existing lines. Bulk delete or whole-file
   rewrite is not allowed unless the user explicitly says "reset".
5. Re-read the file before writing. Another agent may have updated it.

### Conflict handling

If you see a file matching `*.sync-conflict-YYYYMMDD-HHMMSS-DEVICE.<ext>`
(e.g., `journal.sync-conflict-20260514-150030-LUQF73S.md`):

1. Do not silently merge. Show the user a diff between the conflict file
   and its canonical counterpart.
2. Wait for the user's explicit resolution decision.
3. Once given, execute it on the user's behalf (delete the conflict,
   keep the conflict instead, or apply a manual merge per the user's
   instruction). The user has provided the human judgment this rule
   protects.

The device prefix (e.g., LUQF73S) is a diagnostic clue from Syncthing's
conflict filename. It is not evidence of which user edit should win.

Example spoke files (skeletal templates)

Each spoke is a minimal markdown file. The agent writes these as templates; the user fills in details over time.

personal/travel.md

# Travel

## State
(none yet)

## Event log

projects/web-app.md

# Web app

## State
(none yet)

## Event log

projects/mobile-app.md

# Mobile app

## State
(none yet)

## Event log

ops/servers.md

# Servers

## State
(none yet)

## Event log

notes/journal.md

# Journal

## Event log

reference/links.md

# Links

## References
(none yet)

Verification commands

Defensive bash, whitespace-safe, POSIX where possible:

# 1. Confirm INDEX.md links resolve (whitespace-safe, no word splitting).
# Note: this regex parses only the simple inline-link form used in INDEX.md,
# i.e. `[label](relative/path.md)`. It does not handle reference-style links,
# escaped parentheses, or paths with embedded `)` characters. Acceptable here
# because the template forbids such forms; if you customize INDEX.md beyond
# the template, replace this with a proper Markdown parser.
cd "<vault-path>" || exit 1
grep -oE '\([^)]+\.md\)' INDEX.md | tr -d '()' | while IFS= read -r f; do
  [ -f "$f" ] || printf 'Missing: %s\n' "$f"
done

# 2. Confirm conflict glob works (prints nothing on a clean vault)
find . -type f -name '*.sync-conflict-*'

# 3. Confirm no credential-shaped files exist (explicit grouping for -o precedence).
# Pattern set MUST match the stop-condition list below. If you add a pattern to
# one, add it to the other; the two are intentionally synchronized.
find . -type f \( -name '.env' -o -name '*.pem' -o -name 'id_rsa' -o -name 'id_ed25519' -o -name '*token*' -o -name '*secret*' -o -name '*key.json' \)

# 4. Confirm vault structure (no tree dependency; tree is not on default macOS)
find . -maxdepth 2 -type f -not -path '*/.*' | sort

Stop conditions

The agent must halt and ask the user if any of these are true:

• If *.sync-conflict-* files already exist in the vault path: stop. Show the user a diff between canonical and conflict. Wait for an explicit resolution decision; once given, execute it (delete conflict, keep conflict instead, or apply manual merge) before proceeding with vault setup.
• If .env, .pem, id_rsa, id_ed25519, or any file matching credential patterns (*token*, *secret*, *key.json) is found in or near the vault path: stop. Do not read its contents. Ask the user how to proceed.
• If INDEX.md already exists at the target path: stop. Ask before overwriting or restructuring. The existing INDEX.md may reflect the user's accumulated work.
• If the vault path is missing, ambiguous, or hardcoded to an unavailable path: stop. Ask the user for the correct path.
• If the agent's own config file (CLAUDE.md / AGENTS.md / SOUL.md) already contains vault rules: update minimally instead of duplicating the block. Look for the existing ## Shared Vault section and align it with the snippet, do not append a second block.
• If any existing file in the vault appears to contain real identifiers, exact financial amounts, or secrets: stop. Primary detection is filename-based (see the credential pattern set in the verification command and the matching list above). If a content scan is needed, the agent must use local tooling (e.g., grep -l for file-level match, or a regex counter that emits only counts and category labels) that produces a summary only. The agent must never print the matched line, surrounding content, or any extracted token. Report only the file path and the reason category (e.g., "filename matches credential pattern", "content scan reported >0 hits for credit-card-shaped sequences"). Ask the user how to proceed.

Closing

When verification passes, the cross-agent memory contract is live on top of the Syncthing folder. Any agent on any machine reads INDEX.md and operates on the same shared state.