echoes-vault-opencode

AI agents forget everything when a session ends. EchoesVault gives OpenCode a persistent, file-based memory: architectural decisions, daily work logs, and a searchable project encyclopedia — all stored as plain Markdown in your repository.

Features

• Google OKF Compliant — EchoesVault uses Google's Open Knowledge Format (OKF) under the hood. Your knowledge base is 100% interoperable with standard AI parsers and renders natively on GitHub and GitLab.
• Zero context loss — start every session exactly where you left off. /echoes-start reads the last 3 daily logs and the full knowledge index and feeds them to the AI automatically.
• Zero setup — on first load the plugin creates the entire vault structure, slash commands, and agent skills by itself. Nothing to configure.
• Obsidian-compatible vault — EchoesVault/ is a valid Obsidian vault. Open it in Obsidian at any time for visual navigation, graph view, and search.
• ADR-style documentation — the AI is instructed to write with maximum technical density: API contracts, configuration records, and Architectural Decision Records — not chat transcripts.
• Active memory management — the AI logs intermediate notes mid-session via echoes_append_to_daily_log, not just at the end. Context is never lost to a crash or accidental close.
• Deprecation over deletion — outdated pages are marked > [!warning] DEPRECATED and linked to their replacement. The full history is always preserved.
• Safe and idempotent — commands and skills are only created if they don't exist. Restarting OpenCode never overwrites user edits.

Vault structure

The plugin creates and manages the following directory inside your project:

EchoesVault/
├── index.md      — master registry: one-line description of every page
├── pages/        — project encyclopedia (Markdown, YAML frontmatter, [[wikilinks]])
├── daily/        — session work logs (YYYY-MM-DD.md)
├── assets/       — diagrams, schematics, hardware pinouts
└── raw/          — read-only source materials

Every page in pages/ starts with YAML frontmatter. The type property is strictly enforced to maintain OKF compliance:

---
type: architecture
stack: [nestjs, react]
status: active
---

Requirements

• OpenCode >= 1.16.0

Installation

Via OpenCode UI (recommended)

1. Press control + P to open the command palette
2. Select Install plugin
3. Enter the package name: echoes-vault-opencode
4. Restart OpenCode

Manual

Add the plugin to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["echoes-vault-opencode"]
}

OpenCode installs the package automatically via Bun on next startup. On first run the plugin bootstraps the vault, registers the slash commands, and installs the agent skills — no manual steps required.

Usage

Typical session workflow

1. First time in a project — initialize the vault:

/echoes-init

The AI reads EchoesVault/index.md, acknowledges the rules, and lists any existing knowledge. On a fresh vault it confirms initialization.

2. Start of every subsequent session — restore context:

/echoes-start

Reads the last 3 daily logs and the full index, then summarizes where you left off and what the immediate next steps are. Also lints the index for duplicates or contradictions.

3. Work normally. During the session the AI uses the vault tools autonomously:

• logs intermediate decisions to the daily scratchpad,
• searches existing pages before writing new code,
• creates or updates encyclopedia pages when architecture changes.

4. End of session — save everything:

/echoes-end

The AI distills the session into a dense technical summary, writes new encyclopedia pages for any concepts decided today, and updates the index. All via a single tool call.

Slash commands reference

AI tools reference

These tools are available to the AI during any session.

Agent skills reference

Skills guide the AI on when and how to use the tools above. They are loaded on-demand via the OpenCode skill tool.

License

MIT