v1.0.0 — Agent-Neutral Project Memory

EchoesVault v1.0.0 — Agent-Neutral Project Memory

EchoesVault 1.0 introduces a shared, repository-portable memory protocol for Codex, OpenCode,
Claude Code, and other coding agents.

The vault is no longer coupled to one agent's plugin implementation. Every supported agent reads
the same protocol and uses the same local storage engine, validation rules, lock, deterministic
index, and merge-safe daily-log layout.

Highlights

• Agent Protocol 1.0.0
• Repository-portable Python runtime
• Codex, OpenCode, and Claude project adapters
• Managed AGENTS.md and CLAUDE.md integration
• Protocol compatibility checks that fail safely before writes
• Shared cross-agent write lock
• Optional agent provenance in daily and session logs
• Automatic migration from EchoesVault 0.2.x
• Safe migration of recognized legacy OpenCode commands

One protocol for every agent

Initialization now creates:

EchoesVault/AGENT_PROTOCOL.md
EchoesVault/.echoes-vault.json
.echoes-vault/echoes_vault.py
AGENTS.md
CLAUDE.md
.claude/skills/echoes-vault/SKILL.md
.opencode/skills/echoes-vault/SKILL.md
.opencode/commands/echoes-init.md
.opencode/commands/echoes-start.md
.opencode/commands/echoes-status.md
.opencode/commands/echoes-end.md

AGENTS.md and CLAUDE.md receive a delimited EchoesVault block. Existing instructions outside
the managed block are preserved.

The initialization marker now declares:

{
  "schemaVersion": 3,
  "protocolVersion": "1.0.0",
  "generatedIndex": true,
  "dailyLayout": "unique-files-v1",
  "runtime": ".echoes-vault/echoes_vault.py",
  "requiredFrontmatter": ["type", "stack", "status", "summary"]
}

An incompatible runtime stops before writing and asks for an adapter upgrade instead of guessing
how to mutate the vault.

Portable storage engine

The same dependency-free Python runtime is committed into every initialized repository:

python3 .echoes-vault/echoes_vault.py --workspace . <command>

Available commands include:

• init
• protocol
• configure-agents
• start
• status
• search
• append
• hash
• upsert
• end
• rebuild-index

This gives agents without a dedicated EchoesVault plugin access to the same safe storage contract.

OpenCode compatibility

Protocol-aware project commands are generated for OpenCode. Recognized commands created by older
EchoesVault releases are migrated to use the portable runtime.

Legacy tools that directly edit EchoesVault/index.md or append to a shared
daily/YYYY-MM-DD.md file must not be used with protocol 1.0 vaults.

Claude Code compatibility

Claude receives:

• a managed protocol notice in CLAUDE.md;
• a project-local .claude/skills/echoes-vault/SKILL.md adapter;
• access to the same portable runtime used by Codex and OpenCode.

Cross-agent log provenance

append and end payloads accept an optional agent field:

{
  "entry": "- Confirmed the shared authentication contract.",
  "agent": "claude"
}

The normalized agent name is recorded in both the unique filename and the Markdown entry.

Agent-neutral runtime state

Machine-local state and locking moved from .codex/ to .echoes-vault/:

.echoes-vault/state.json
.echoes-vault/lock

Both files are ignored by Git. All agents operating in the same working tree now share one lock.

The legacy .codex/echoes-vault-state.json file is read automatically during migration.

Upgrade from 0.2.x

After installing 1.0.0, initialize each existing vault once:

python3 /path/to/echoes-vault-codex/scripts/echoes_vault.py --workspace . init

This operation:

• upgrades the marker to protocol 1.0.0;
• migrates local session state;
• installs the portable runtime and protocol document;
• adds or updates managed agent instructions;
• installs Claude and OpenCode project adapters;
• replaces recognized legacy OpenCode EchoesVault commands;
• preserves knowledge pages, logs, assets, raw files, and unrelated agent instructions.

If EchoesVault/index.md is still tracked by Git, remove it from the Git index while preserving the
local generated file:

git rm --cached EchoesVault/index.md

Git contract

Commit the portable runtime, protocol, adapters, pages, unique daily files, assets, and raw sources.

Do not commit:

EchoesVault/index.md
.echoes-vault/state.json
.echoes-vault/lock

Validation

Version 1.0.0 includes automated coverage for:

• portable runtime execution;
• agent-guide preservation and idempotency;
• recognized legacy OpenCode command migration;
• unsupported-protocol rejection;
• legacy Codex state migration;
• Codex, OpenCode, and Claude log provenance;
• deterministic index generation;
• concurrent writes;
• real multi-branch Git merges;
• conflict-marker and metadata diagnostics.

No CI/CD integration, daemon, network service, API key, or background watcher is required at
runtime.