opencode-episodic-memory
AGENTS.md4 starsChanged 48 days agoMITView on GitHub
Inspired by obra/episodic-memory. Semantic search over past OpenCode conversations via native plugin tools. - ARCHITECTURE.md — system overview with Mermaid diagrams (data model, write/read paths, design decisions); keep in sync when changing the pipeline - src/reader.ts — read-only access to ~/.local/share/opencode/opencode.db (v2 session_v2/session_message, JSON blobs in data) - src/parser.ts — transcript → condensed exchanges; exclusion marker handling - src/embed.ts — embedding host/client; lazy Node sidecar by default - src/embed-sidecar.mjs — persistent Node 20+ Transformers.js server (NDJSON) - src/embed-inline.ts — explicit…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 75
Hybrid (vector+BM25 RRF) search is opt-in, NOT the default: search() defaults to pure vector.
- Very specific: line 145
Verify empirically before building (see spikes/).
- Very specific: line 147
When bumping @huggingface/transformers, capture baseline embeddings pre-bump and compare cosine post-bump before assuming existing indexes …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
opencode-episodic-memory — agent context
Inspired by obra/episodic-memory. Semantic search over past OpenCode conversations via native plugin tools.
Layout
ARCHITECTURE.md— system overview with Mermaid diagrams (data model, write/read paths, design decisions); keep in sync when changing the pipelinesrc/reader.ts— read-only access to~/.local/share/opencode/opencode.db(v2 session_v2/session_message, JSON blobs indata)src/parser.ts— transcript → condensed exchanges; exclusion marker handlingsrc/embed.ts— embedding host/client; lazy Node sidecar by defaultsrc/embed-sidecar.mjs— persistent Node 20+ Transformers.js server (NDJSON)src/embed-inline.ts— explicit lazy inline escape hatch; unsafe in affected Bun hostssrc/store.ts— index SQLite DB; brute-force cosine vector search (the swap point if an ANN index is ever needed) + FTS5 BM25 lexical search, fused on demand via reciprocal rank fusion. Two-phase: score candidates on embeddings/BM25 only, hydrate text/title/directory/source anchor for the top-K winners.src/indexer.ts— incremental sync, watermark =session.time_updatedsrc/cli.ts—bun run src/cli.ts sync|search|read|stats|doctorplugin/v2.ts,plugin/shared.ts— v2 entrypoint and tools + settled-session reindex;plugin/log.tsappends to OpenCode's log fileskills/remembering-conversations/SKILL.md— recall-behavior skilldocs/embedding-model-eval.md— model survey + empirical eval behind the snowflake choicedocs/alternatives.md— comparison with other OpenCode memory plugins (opencode-mem, codemem, memsearch, ...) and why this one existsdocs/opencode-2-compatibility.md— reported OpenCode 2.0 source-store changes, impact on this reader, and migration verification checklisteval/— reusable model-comparison harness; private inputs/outputs (queries.ts,corpus.json,results-*) live ineval/private/, which is gitignored wholesale — drop any new private artifact there, no gitignore edit needed; see its README- Tests:
bun test(parser/store/reader/sidecar smoke tests);bun run typecheck spikes/— Phase 0 verification + plugin harness (run withbun run)
Hard-won facts (don't rediscover)
- Embedding model is
Snowflake/snowflake-arctic-embed-m-v1.5(q8, CLS pooling) with the BGE-style query prefix on queries only (Snowflake uses the identical prompt). Chosen by empirical eval on our real corpus over bge-small-en-v1.5, nomic v1.5, gte-modernbert, granite-r2, embeddinggemma — seedocs/embedding-model-eval.md. Key win: negatives score ≤ ~0.33 vs bge's ~0.66, so minScore thresholding is viable. Score scale: true hits ~0.4–0.73, median ~0.56. Pooling MUST beclsfor this model, notmean. Xenova mirrors of nomic/snowflake 401 now — use official repos' own ONNX exports. - Truncate embedded text at 2000 chars (upstream measured quality peaks there); the stored chunk text may be longer for display, embed.ts truncates.
- Sync (CLI
syncand the plugin's per-session settled-session reindex alike) prunes index sessions that no longer exist in the source DB (deleted conversations would otherwise linger with stale-model embeddings), and search skips embedding rows whose byteLength ≠ dims×4 — a mixed-model index can never crash or corrupt search. Both bugs were found during the bge→snowflake migration (12 orphaned 384-dim chunks crashed a 768-dim query). - Chunks persist the nullable source-user
anchor_message_idfor progressive disclosure: search renders it, thenepisodic_read_windowreads a bounded (0-20 messages each side) live-source window. The anchor migration uses onlyALTER TABLE ... ADD COLUMN, marks existing sessions stale for normal sync, and must never rebuildchunksor disturb its implicit rowids/FTS mapping. bun:sqlitedoes not support dynamic extension loading — sqlite-vec cannot work inside OpenCode plugins. Hence brute-force cosine over Float32 blobs. FTS5, by contrast, is compiled into bun:sqlite (a static module, not a loadable extension — verified inspikes/fts5-check.ts), so lexical BM25 search IS available. The FTS index (chunks_fts) is an external-content FTS5 table overchunks.text, kept in sync by triggers onchunks(robust to any write path, not just replaceSessionChunks) and backfilled once for pre-FTS index DBs via aPRAGMA user_version-gated'rebuild'(COUNT(*) on an external-content FTS returns the content count, so it can't detect an un-backfilled index — user_version is the reliable signal). Never VACUUM index.db: the FTS5 external-content mapping rideschunks' IMPLICIT rowid (the PK is(session_id, seq), no explicitINTEGER PRIMARY KEYalias), and VACUUM may renumber implicit rowids — silently misaligning every FTS posting from its chunk row. If VACUUM is ever needed, first migratechunksto an explicitrowid INTEGER PRIMARY KEY.- Hybrid (vector+BM25 RRF) search is opt-in, NOT the default. search()
defaults to pure vector; pass
hybrid: true+queryText(CLI--hybrid, pluginmode: "hybrid") to fuse. Empirically on this corpus BM25 matches injected boilerplate (the[MEMORY]preamble, tool descriptions) and RRF then drags those noise hits above genuine semantic matches — e.g. "episodic memory architecture decisions" surfaced "TealHQ Cloudflare deployment" / "3-month financial projection" at the top. minScore is applied to the vector arm BEFORE fusion (its calibration is cosine, not BM25). Hybrid hits carry fused RRF scores (~0.03), a DIFFERENT scale from the vector arm's cosine (~0.4–0.7) — don't judge them against the documented cosine thresholds; CLI/plugin output labels themrrf:(notscore:) for this reason.textSearch/mode:"text"is pure BM25 (quoted-term MATCH to neutralize FTS operators; the LIKE fallback fires ONLY on an FTS5 syntax error — any other SqliteError rethrows so a corrupt index can't silently degrade to unranked results). An empty/ whitespace-only text query returns[](the old LIKE scan returned recent chunks). - OpenCode sessions live in one SQLite DB (WAL mode; concurrent read-only access is safe), NOT JSONL transcripts like Claude Code.
- The v2 source uses
session_v2/session_messageand nested content. OpenCode's migration copies old sessions into these tables, retaining IDs and timestamps. Runtime reads require complete v2 tables and ignore retained v1 tables. The-v2index status forces one reindex of older statuses. Seedocs/opencode-2-compatibility.mdbefore changing privacy/anchor handling. - Runtime validation of
opencode.dbreads uses Zod (src/reader.ts), split by failure mode: structural rows (listSessions/getSession/getTranscriptrow envelopes — the id/time_created/data columns) throw via.parse(), so OpenCode schema drift surfaces loudly instead of being silently mis-read; the JSONdatablobs (message role, part contents) degrade per-row to"unknown"/undefinedvia.catch(), so one corrupt or unfamiliar blob can't abort a whole transcript read (the parser already filters unknown types/roles). Because the internalgetTranscriptthrows on structural drift andsyncAllreads every session throughgetTranscriptChecked(which calls it), a structural drift aborts the whole bulk sync (all-or-nothing) — intentional fail-loud; the plugin's background reindex catches and logs it. The index DB (store.ts) deliberately stays ondb.prepare<T>()typed casts — we own that schema end to end, so runtime validation adds no value there. Keep the no-asrule: narrow via schemas, never assertions (the two documentedas Float32Arraycasts inembed.ts/evalare the sanctioned transformers.js typing-gap exceptions). - Plugin runs inside OpenCode's Bun runtime. By default, Transformers.js and its
native ML addons (
onnxruntime-node,sharp) load only in the persistent Node 20+ sidecar, never on plugin import.EPISODIC_EMBED_MODE=inlineis an explicit escape hatch that lazily imports the backend on the first embedding request in Bun; it is unsafe in affected OpenCode/Bun versions. Text search and transcript reads do not embed and therefore work without Node.onnxruntime-nodeships platform binaries in its npm tarball;trustedDependenciesonly affects contributors. - The
DO NOT INDEX THIS CHATexclusion marker is matched as a bare substring anywhere in any message part (broader than upstream's full instruction-tag match), so it also fires on conversations that merely quote the phrase — including conversations about building this tool. The AUTHORITATIVE check istranscriptHasMarker()in reader.ts, which substring-matches the RAWdatacolumn (instr, exact case) with no JSON parsing — the marker must not depend on blob parseability, since the blob pipeline degrades unparseable parts totext: undefined. Production reads use eithergetTranscriptChecked()or the snapshot-gatedgetTranscriptContext()(reader.ts); both run that raw check BEFORE materializing anything and return privacy-safe results — so indexing (indexer.ts),episodic_read_window,episodic_read_session, and CLIreadcannot bypass the gate by forgetting a manual check. The rawgetTranscriptis module-internal (not exported);transcriptHasMarkerstays exported as the authoritative primitive (directly tested in reader.test.ts).hasExcludeMarker()in parser.ts is a cheaper parsed-text fast path kept for parseTranscript's in-memory flow; EXCLUDE_MARKER lives in reader.ts and is re-exported by parser.ts. - The v2 plugin uses
Plugin.definefrom@opencode/pluginand exports the same definition from root and./server. No v1 runtime adapter remains.
Conventions
- Verify empirically before building (see
spikes/); runbun run spikes/entrypoint-smoke.tsafter changing the plugin. - When bumping
@huggingface/transformers, capture baseline embeddings pre-bump and compare cosine post-bump before assuming existing indexes stay valid (v3↔v4 happened to be identical; don't assume that holds). - Reindex manually with
bun run src/cli.ts sync(idempotent; watermark-based). - Releases follow
docs/RELEASE.md; pushing a matchingvX.Y.Ztag runs the OIDC trusted-publishing workflow and creates the GitHub release. The artifact gate isbash spikes/pack-smoke.sh(pack → clean install → import → real Node-sidecar embed). Keepsrc/embed-sidecar.mjsincluded in the npm artifact and run the offline fake-sidecar protocol tests without downloading a model. OpenCode v2 does NOT auto-update npm plugins, but@latestis safe: dogfood configs use"opencode-episodic-memory@latest", and after a releaseopencode plugin updateinstalls the new version into~/.cache/opencode/npm/<spec>/<timestamp>/(opencode plugin checkshows what is installed). Restart alone never picks up a new publish. - Config is env-var only (
EPISODIC_*), no config file yet (YAGNI).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

