agentleFS
robertn702robertn702/opencode-episodic-memory/AGENTS.md

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
  1. Very specific:

    Hybrid (vector+BM25 RRF) search is opt-in, NOT the default: search() defaults to pure vector.

    line 75
  2. Very specific:

    Verify empirically before building (see spikes/).

    line 145
  3. Very specific:

    When bumping @huggingface/transformers, capture baseline embeddings pre-bump and compare cosine post-bump before assuming existing indexes …

    line 147

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 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 lazy inline escape hatch; unsafe in affected Bun hosts
  • src/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_updated
  • src/cli.ts — bun run src/cli.ts sync|search|read|stats|doctor
  • plugin/v2.ts, plugin/shared.ts — v2 entrypoint and tools + settled-session reindex; plugin/log.ts appends to OpenCode's log file
  • skills/remembering-conversations/SKILL.md — recall-behavior skill
  • docs/embedding-model-eval.md — model survey + empirical eval behind the snowflake choice
  • docs/alternatives.md — comparison with other OpenCode memory plugins (opencode-mem, codemem, memsearch, ...) and why this one exists
  • docs/opencode-2-compatibility.md — reported OpenCode 2.0 source-store changes, impact on this reader, and migration verification checklist
  • eval/ — reusable model-comparison harness; private inputs/outputs (queries.ts, corpus.json, results-*) live in eval/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 with bun 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 — see docs/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 be cls for this model, not mean. 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 sync and 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_id for progressive disclosure: search renders it, then episodic_read_window reads a bounded (0-20 messages each side) live-source window. The anchor migration uses only ALTER TABLE ... ADD COLUMN, marks existing sessions stale for normal sync, and must never rebuild chunks or disturb its implicit rowids/FTS mapping.
  • bun:sqlite does 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 in spikes/fts5-check.ts), so lexical BM25 search IS available. The FTS index (chunks_fts) is an external-content FTS5 table over chunks.text, kept in sync by triggers on chunks (robust to any write path, not just replaceSessionChunks) and backfilled once for pre-FTS index DBs via a PRAGMA 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 rides chunks' IMPLICIT rowid (the PK is (session_id, seq), no explicit INTEGER PRIMARY KEY alias), and VACUUM may renumber implicit rowids — silently misaligning every FTS posting from its chunk row. If VACUUM is ever needed, first migrate chunks to an explicit rowid 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, plugin mode: "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 them rrf: (not score:) 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_message and 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 -v2 index status forces one reindex of older statuses. See docs/opencode-2-compatibility.md before changing privacy/anchor handling.
  • Runtime validation of opencode.db reads uses Zod (src/reader.ts), split by failure mode: structural rows (listSessions/getSession/getTranscript row envelopes — the id/time_created/data columns) throw via .parse(), so OpenCode schema drift surfaces loudly instead of being silently mis-read; the JSON data blobs (message role, part contents) degrade per-row to "unknown"/undefined via .catch(), so one corrupt or unfamiliar blob can't abort a whole transcript read (the parser already filters unknown types/roles). Because the internal getTranscript throws on structural drift and syncAll reads every session through getTranscriptChecked (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 on db.prepare<T>() typed casts — we own that schema end to end, so runtime validation adds no value there. Keep the no-as rule: narrow via schemas, never assertions (the two documented as Float32Array casts in embed.ts/eval are 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=inline is 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-node ships platform binaries in its npm tarball; trustedDependencies only affects contributors.
  • The DO NOT INDEX THIS CHAT exclusion 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 is transcriptHasMarker() in reader.ts, which substring-matches the RAW data column (instr, exact case) with no JSON parsing — the marker must not depend on blob parseability, since the blob pipeline degrades unparseable parts to text: undefined. Production reads use either getTranscriptChecked() or the snapshot-gated getTranscriptContext() (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 CLI read cannot bypass the gate by forgetting a manual check. The raw getTranscript is module-internal (not exported); transcriptHasMarker stays 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.define from @opencode/plugin and exports the same definition from root and ./server. No v1 runtime adapter remains.

Conventions

  • Verify empirically before building (see spikes/); run bun run spikes/entrypoint-smoke.ts after 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 matching vX.Y.Z tag runs the OIDC trusted-publishing workflow and creates the GitHub release. The artifact gate is bash spikes/pack-smoke.sh (pack → clean install → import → real Node-sidecar embed). Keep src/embed-sidecar.mjs included 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 @latest is safe: dogfood configs use "opencode-episodic-memory@latest", and after a release opencode plugin update installs the new version into ~/.cache/opencode/npm/<spec>/<timestamp>/ (opencode plugin check shows what is installed). Restart alone never picks up a new publish.
  • Config is env-var only (EPISODIC_*), no config file yet (YAGNI).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.