echoes-vault-opencode 1.2.3 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/EchoesProtocol.md +1097 -0
- package/README.md +150 -99
- package/index.ts +178 -430
- package/package.json +17 -6
- package/prompts/commands/echoes-end.md +9 -16
- package/prompts/commands/echoes-init.md +7 -31
- package/prompts/commands/echoes-start.md +6 -25
- package/prompts/commands/echoes-status.md +4 -32
- package/runtime.ts +176 -0
- package/scripts/echoes_vault.py +2454 -0
- package/tui.tsx +75 -75
- package/prompts/skills/echoes-append-to-daily-log.md +0 -22
- package/prompts/skills/echoes-create-or-update-page.md +0 -22
- package/prompts/skills/echoes-search-vault-pages.md +0 -19
package/README.md
CHANGED
|
@@ -1,68 +1,55 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<img src="https://raw.githubusercontent.com/psinetron/echoes-vault-opencode/main/images/EchoesVault.png" alt="EchoesVault" width="200" />
|
|
3
|
-
<h1>EchoesVault</h1>
|
|
4
|
-
<p>
|
|
3
|
+
<h1>EchoesVault for OpenCode</h1>
|
|
4
|
+
<p>An OpenCode adapter for repository-local, agent-neutral project memory.</p>
|
|
5
5
|
|
|
6
6
|
[](https://www.npmjs.com/package/echoes-vault-opencode)
|
|
7
7
|
[](LICENSE)
|
|
8
|
-
[](https://opencode.ai/docs/
|
|
8
|
+
[](https://opencode.ai/docs/plugins/)
|
|
9
9
|
[](https://bundledex.net/bundles/echoes-vault-opencode/)
|
|
10
10
|
</div>
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
EchoesVault stores architectural decisions, verified fixes, daily work notes, and other durable
|
|
15
|
+
project knowledge as Markdown in the repository. Version 2 is a thin adapter for EchoesVault
|
|
16
|
+
Protocol 1.0.0: OpenCode, Codex, Claude Code, and scripts all delegate writes to the same
|
|
17
|
+
project-local runtime and share one knowledge base.
|
|
15
18
|
|
|
16
|
-
##
|
|
19
|
+
## Why version 2
|
|
17
20
|
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
|
|
21
|
-
- **
|
|
22
|
-
-
|
|
23
|
-
- **
|
|
24
|
-
- **
|
|
25
|
-
|
|
21
|
+
- **One writer across agents** — every mutation uses `.echoes-vault/echoes_vault.py`.
|
|
22
|
+
- **Git-friendly collaboration** — daily entries use unique UTC-sortable files and the generated
|
|
23
|
+
index is ignored, removing the usual cross-branch hot spots.
|
|
24
|
+
- **Safe concurrent updates** — a shared local lock, atomic file replacement, and current-content
|
|
25
|
+
SHA-256 checks prevent silent overwrites.
|
|
26
|
+
- **Explicit lifecycle** — installing the plugin never initializes or migrates a repository.
|
|
27
|
+
- **Agent-neutral state** — all integrations use `.echoes-vault/state.json`; state is local and
|
|
28
|
+
disposable, while Markdown remains the source of truth.
|
|
29
|
+
- **Deterministic discovery** — `EchoesVault/index.md` is generated from validated page metadata and
|
|
30
|
+
is never edited as authored knowledge.
|
|
31
|
+
- **Portable and inspectable** — no network service, database, API key, or third-party Python
|
|
32
|
+
package is required at runtime.
|
|
26
33
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
The plugin creates and manages the following directory inside your project:
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
EchoesVault/
|
|
33
|
-
├── index.md — master registry: one-line description of every page
|
|
34
|
-
├── pages/ — project encyclopedia (Markdown, YAML frontmatter, [[wikilinks]])
|
|
35
|
-
├── daily/ — session work logs (YYYY-MM-DD.md)
|
|
36
|
-
├── assets/ — diagrams, schematics, hardware pinouts
|
|
37
|
-
└── raw/ — read-only source materials
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
Every page in `pages/` starts with YAML frontmatter. The `type` property is strictly enforced to maintain OKF compliance:
|
|
41
|
-
|
|
42
|
-
```yaml
|
|
43
|
-
---
|
|
44
|
-
type: architecture
|
|
45
|
-
stack: [nestjs, react]
|
|
46
|
-
status: active
|
|
47
|
-
---
|
|
48
|
-
```
|
|
34
|
+
The complete implementer contract is in [EchoesProtocol.md](EchoesProtocol.md).
|
|
49
35
|
|
|
50
36
|
## Requirements
|
|
51
37
|
|
|
52
38
|
- [OpenCode](https://opencode.ai) `>= 1.16.0`
|
|
39
|
+
- Python `>= 3.9` available as `python3`
|
|
53
40
|
|
|
54
|
-
|
|
41
|
+
If Python uses another executable name, set `ECHOES_VAULT_PYTHON` for the OpenCode process.
|
|
55
42
|
|
|
56
|
-
|
|
43
|
+
## Installation
|
|
57
44
|
|
|
58
|
-
|
|
59
|
-
2. Select **Install plugin**
|
|
60
|
-
3. Enter the package name: `echoes-vault-opencode`
|
|
61
|
-
4. Restart OpenCode
|
|
45
|
+
### Via OpenCode UI
|
|
62
46
|
|
|
63
|
-
|
|
47
|
+
1. Press <kbd>control</kbd> + <kbd>P</kbd>.
|
|
48
|
+
2. Select **Install plugin**.
|
|
49
|
+
3. Enter `echoes-vault-opencode`.
|
|
50
|
+
4. Restart OpenCode.
|
|
64
51
|
|
|
65
|
-
|
|
52
|
+
### Via configuration
|
|
66
53
|
|
|
67
54
|
```json
|
|
68
55
|
{
|
|
@@ -71,93 +58,157 @@ Add the plugin to your `opencode.json`:
|
|
|
71
58
|
}
|
|
72
59
|
```
|
|
73
60
|
|
|
74
|
-
|
|
61
|
+
Plugin installation is intentionally read-only for the current repository. Initialize or migrate
|
|
62
|
+
only the repositories where memory is wanted:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
/echoes-init
|
|
66
|
+
```
|
|
75
67
|
|
|
76
|
-
##
|
|
68
|
+
## Repository layout
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
<repository>/
|
|
72
|
+
├── EchoesVault/
|
|
73
|
+
│ ├── .echoes-vault.json # tracked protocol marker
|
|
74
|
+
│ ├── AGENT_PROTOCOL.md # tracked compact agent guide
|
|
75
|
+
│ ├── index.md # ignored deterministic view
|
|
76
|
+
│ ├── pages/ # tracked curated knowledge
|
|
77
|
+
│ ├── daily/YYYY-MM-DD/ # tracked unique session entries
|
|
78
|
+
│ ├── assets/ # tracked referenced assets
|
|
79
|
+
│ └── raw/ # tracked source material
|
|
80
|
+
└── .echoes-vault/
|
|
81
|
+
├── echoes_vault.py # tracked shared writer
|
|
82
|
+
├── state.json # ignored local state
|
|
83
|
+
└── lock # ignored local lock
|
|
84
|
+
```
|
|
77
85
|
|
|
78
|
-
|
|
86
|
+
Knowledge pages require this frontmatter:
|
|
79
87
|
|
|
80
|
-
|
|
88
|
+
```yaml
|
|
89
|
+
---
|
|
90
|
+
type: architecture
|
|
91
|
+
stack: [typescript, python]
|
|
92
|
+
status: active
|
|
93
|
+
summary: OpenCode delegates all EchoesVault mutations to the shared project runtime.
|
|
94
|
+
---
|
|
81
95
|
```
|
|
96
|
+
|
|
97
|
+
The summary must be a non-empty single line of at most 160 characters.
|
|
98
|
+
|
|
99
|
+
## Workflow
|
|
100
|
+
|
|
101
|
+
### Initialize or migrate
|
|
102
|
+
|
|
103
|
+
```text
|
|
82
104
|
/echoes-init
|
|
83
105
|
```
|
|
84
|
-
The AI reads `EchoesVault/index.md`, acknowledges the rules, and lists any existing knowledge. On a fresh vault it confirms initialization.
|
|
85
106
|
|
|
86
|
-
|
|
87
|
-
|
|
107
|
+
This is the only normal entry point that creates or migrates the vault. It installs the portable
|
|
108
|
+
runtime, upgrades recognized legacy OpenCode commands and skills, imports compatible local session
|
|
109
|
+
state, validates page metadata, and rebuilds the generated index. Unknown user-owned adapter files
|
|
110
|
+
are preserved and reported for manual reconciliation.
|
|
111
|
+
|
|
112
|
+
### Restore a session
|
|
113
|
+
|
|
114
|
+
```text
|
|
88
115
|
/echoes-start
|
|
89
116
|
```
|
|
90
|
-
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.
|
|
91
117
|
|
|
92
|
-
|
|
93
|
-
- logs intermediate decisions to the daily scratchpad,
|
|
94
|
-
- searches existing pages before writing new code,
|
|
95
|
-
- creates or updates encyclopedia pages when architecture changes.
|
|
118
|
+
Loads the generated index and the three newest daily entries. It does not load the entire vault.
|
|
96
119
|
|
|
97
|
-
|
|
98
|
-
```
|
|
99
|
-
/echoes-end
|
|
100
|
-
```
|
|
101
|
-
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.
|
|
120
|
+
### Inspect health
|
|
102
121
|
|
|
103
|
-
|
|
122
|
+
```text
|
|
123
|
+
/echoes-status
|
|
124
|
+
```
|
|
104
125
|
|
|
105
|
-
|
|
126
|
+
Reports protocol, runtime, storage, metadata, conflicts, Git readiness, and scale. Status is
|
|
127
|
+
strictly read-only and never initializes, migrates, hydrates, or repairs files.
|
|
106
128
|
|
|
107
|
-
###
|
|
129
|
+
### Finalize a session
|
|
108
130
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
| `/echoes-start` | Start session — restore context from the last 3 daily logs and the index |
|
|
113
|
-
| `/echoes-end` | End session — distill and commit session memory to the vault |
|
|
114
|
-
| `/echoes-status` | Report vault health, statistics, and scalability |
|
|
131
|
+
```text
|
|
132
|
+
/echoes-end
|
|
133
|
+
```
|
|
115
134
|
|
|
116
|
-
|
|
135
|
+
Finalization is available only after this explicit user command. It writes one unique session
|
|
136
|
+
summary and optional validated knowledge pages. Existing pages require a fresh SHA-256 obtained
|
|
137
|
+
immediately before the update.
|
|
117
138
|
|
|
118
|
-
|
|
139
|
+
## OpenCode tools
|
|
119
140
|
|
|
120
|
-
| Tool |
|
|
141
|
+
| Tool | Purpose |
|
|
121
142
|
|---|---|
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
|
|
127
|
-
|
|
143
|
+
| `echoes_activate_vault` | Explicit initialization or migration after `/echoes-init` |
|
|
144
|
+
| `echoes_start_session` | Restore index and recent entries after `/echoes-start` |
|
|
145
|
+
| `echoes_vault_status` | Read-only health card |
|
|
146
|
+
| `echoes_append_to_daily_log` | Write one unique intermediate daily entry |
|
|
147
|
+
| `echoes_search_vault_pages` | Targeted search across curated pages |
|
|
148
|
+
| `echoes_hash_vault_page` | Get the current hash required for a page replacement |
|
|
149
|
+
| `echoes_create_or_update_page` | Validated page creation or hash-protected replacement |
|
|
150
|
+
| `echoes_hydrate_vault` | Rebuild only ignored local index/state files |
|
|
151
|
+
| `commit_memory_to_echoes_vault` | Explicit final session distillation after `/echoes-end` |
|
|
152
|
+
|
|
153
|
+
Tools invoke Python as an argument array, send Markdown payloads over standard input, keep stdout
|
|
154
|
+
and stderr separate, and propagate every non-zero runtime exit as a failed tool call.
|
|
155
|
+
|
|
156
|
+
## Using the same vault from different computers
|
|
157
|
+
|
|
158
|
+
Commit durable protocol files, the portable runtime, pages, daily entries, assets, raw material,
|
|
159
|
+
and managed agent adapters. Do not commit:
|
|
160
|
+
|
|
161
|
+
```text
|
|
162
|
+
EchoesVault/index.md
|
|
163
|
+
.echoes-vault/state.json
|
|
164
|
+
.echoes-vault/lock
|
|
165
|
+
.opencode/echoes-state.json
|
|
166
|
+
.codex/echoes-vault-state.json
|
|
167
|
+
```
|
|
128
168
|
|
|
129
|
-
|
|
169
|
+
After cloning, `/echoes-start` hydrates the ignored index/state and restores context. Codex and
|
|
170
|
+
OpenCode record their own `lastWriter.agent` and `adapterVersion`, but both use the same protocol,
|
|
171
|
+
runtime, pages, and daily history.
|
|
130
172
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
| `echoes_search_vault_pages` | When to search the vault before generating code |
|
|
135
|
-
| `echoes_create_or_update_page` | When to create vs. update a page, deprecation rules |
|
|
173
|
+
The local lock coordinates processes in one checkout. Git still handles edits made in different
|
|
174
|
+
clones. Unique daily files normally merge independently; edits to the same curated page require
|
|
175
|
+
ordinary semantic conflict resolution.
|
|
136
176
|
|
|
137
|
-
##
|
|
177
|
+
## Migrating from EchoesVault OpenCode 1.x
|
|
138
178
|
|
|
139
|
-
|
|
179
|
+
1. Install version 2 and restart OpenCode. Loading the plugin does not change the repository.
|
|
180
|
+
2. Run `/echoes-status` for a read-only preview. A legacy vault is reported as requiring migration.
|
|
181
|
+
3. Run `/echoes-init` explicitly.
|
|
182
|
+
4. Review the returned adapter and Git-readiness warnings.
|
|
183
|
+
5. Commit the durable files listed by the status card; untrack legacy local/generated files if
|
|
184
|
+
requested by its suggested Git commands.
|
|
140
185
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
186
|
+
The migrator understands the old `.opencode/echoes-state.json`, flat daily logs, legacy index
|
|
187
|
+
descriptions, and recognized EchoesVault commands/skills. It never silently overwrites unknown
|
|
188
|
+
user-owned files.
|
|
144
189
|
|
|
145
|
-
|
|
190
|
+
## Development
|
|
146
191
|
|
|
147
|
-
|
|
192
|
+
Development tests require Node `>= 22.6` for native TypeScript execution.
|
|
148
193
|
|
|
149
|
-
|
|
194
|
+
```sh
|
|
195
|
+
npm install
|
|
196
|
+
npm test
|
|
197
|
+
npm run pack:check
|
|
198
|
+
```
|
|
150
199
|
|
|
151
|
-
|
|
200
|
+
`npm test` type-checks the server adapter, TUI, and tests, then runs bridge-level lifecycle,
|
|
201
|
+
migration, write-safety, and runtime-integrity checks against the bundled reference runtime.
|
|
152
202
|
|
|
153
|
-
|
|
154
|
-
The easiest way to support EchoesVault is to click the **Star** 🌟 button at the top of this repository. It helps more developers discover the tool and encourages further development.
|
|
203
|
+
## Updating
|
|
155
204
|
|
|
156
|
-
|
|
157
|
-
|
|
205
|
+
```sh
|
|
206
|
+
opencode plugin echoes-vault-opencode@X.X.X --force
|
|
207
|
+
```
|
|
158
208
|
|
|
159
|
-
|
|
160
|
-
|
|
209
|
+
Restart OpenCode after updating. A newer plugin may delegate to a newer compatible project runtime
|
|
210
|
+
and will never downgrade it; project runtime changes happen only through explicit initialization or
|
|
211
|
+
upgrade workflows.
|
|
161
212
|
|
|
162
213
|
## License
|
|
163
214
|
|