opencode-memory — v3 (portable)

A self-contained, harness-agnostic memory system for coding agents. One plugin, one engine, zero claim on any one person's machine.

What this is

This package is the v3 of a memory system that grew out of a single developer's rig. v3 is the version written for anyone's machine: it installs on a computer that isn't the author's, it runs for someone who isn't the author, and it carries no personal data — no user facts, no transcripts, no machine paths, no embedded history.

It is built as one plugin (plugins/memory-plugin.ts) that carries every surface of the system, backed by a harness-agnostic Python engine that only depends on the standard library plus sqlite-vec:

Surface	What it does
Core memory	Always-on entries (constitution, identity, operating, project) compiled into context each session.
Hybrid store	SQLite + sqlite-vec + FTS5 atomic entries: semantic + lexical recall, tamper-evident audit chain.
Warm tier	Small topic "neurons" that fire only on keyword match — zero token cost when unfired.
Claim audit	Deterministic anti-overclaim gate: degrades unsupported strong claims mechanically, no LLM in the judgment path.
Drift ledger	SHA-256 checksums on core content; authorised growth re-anchors, unauthorised drift auto-restores.
Growth	Sessions archived at compaction into the store; coherence-gated identity growth.
Compat check	Automatic assessment when the host harness updates.
Todo continuity	Restores active tasks across sessions.
Domain layer	Portable top-level domains; the user's actual topics are discovered from the store as sub-domains (so the same code serves any user).
Versioning kit	Deterministic semantic versioning + GitHub: vversion (mechanical semver from conventional commits), vrelease (detailed release notes), version-kit/vversion-init (installs the workflow + commit hook + one-line agent directive). GitHub tags are the source of truth.
Graph visualizer	graph-viewer.py + graph-view — interactive live view of the memory graph, store topics, neurons, health and version history (no dependencies, opens in the browser).
Neuron optimization	Warm neurons are atomic store entries fired under a token budget — no size limits, no stored-content splitting. Optimization happens at injection, where it matters.
TUI indicator	sleep-indicator.tsx shows the background memory cycle running.

Design principles

• The model cannot audit itself. The claim-audit gate, the drift ledger, and the coherence gate are deterministic: regex + SQLite + templates. No LLM in the judgment path. (Huang et al. 2310.01798, Kadavath et al. 2303.17580, FactScore — this is built, not cited.)
• The harness persists; the engine is swappable. Memory content lives in the store and ledger, not in the model. Swap the LLM, the memory survives.
• Everything degrades to safe. Any failure skips injection or abstains ("no relevant memory" is correct behaviour, not a bug).
• No hardcoded paths. Every path resolves from OPENCODE_CONFIG_DIR / OPENCODE_MEMORY_DIR / MEMORY_PYTHON, defaulting to ~/.config/opencode.
• Domains are data, not code. The package ships portable top-level domains (software, teaching, media, research, …). Your actual topics — however specific — are discovered from the store and treated as sub-domains under them. The same code serves a guitar teacher and a fintech engineer.

Install

bash install.sh

Requirements: Python ≥ 3.10, and opencode (optional — the engine works from the CLI alone). Optional: Ollama with an embedding model (nomic-embed-text) for semantic recall; without it recall falls back to lexical search / abstention.

The installer:

1. creates a Python venv with sqlite-vec,
2. copies scripts + the plugin into your opencode config,
3. writes an hourly systemd timer (only if systemd is present).

Verify

bash ~/.config/opencode/scripts/canary.sh

The canary suite is a 32-check functional proof of the whole system on a fresh machine. It uses no personal data — every fixture is a neutral synthetic user.

Using the engine standalone (any harness)

The engine is pure Python and has no opencode dependency:

# store a fact
python3 ~/.config/opencode/scripts/memory_store.py add "A durable fact" --topic human
# recall
python3 ~/.config/opencode/scripts/memory_store.py recall "what matters"# health
python3 ~/.config/opencode/scripts/system_status.py

Point it anywhere with environment variables — no code changes needed:

export OPENCODE_MEMORY_DIR=/srv/agent-memory
export MEMORY_PYTHON=/usr/bin/python3

Layout

scripts/ the engine (pure Python, harness-agnostic)
plugins/ one consolidated opencode plugin + one TUI indicator
canary.sh functional self-test
install.sh portable installer
docs/ design + version documentation (see below)

Documentation

Document	What it explains
docs/VERSIONING.md	v1 → v2 → v3 differences and what portability changed
docs/V4_CHANGES.md	everything new in v4 (versioning kit, graph viewer, neuron rebuild, removals)
docs/NEW_SCHEMA.md	the new store schema and the migration from markdown blocks
docs/PRD.md	the full product requirements document
docs/UNIFIED_MODEL.md	the reference architecture ("The Standard")
docs/upgrades/UPGRADE_STACK.md	every upgrade and how it functions
docs/memory-structure/BLOCK_STRUCTURE.md	the tier structure (shape, not data)
docs/research/	the research briefs that informed the design
scripts/REMOVAL_LOG.md	every obsolete function removed and its replacement suggestion

Acknowledgements

This is v3 of a system that began as one developer's rig. The v1 → v2 → v3 progression was audited by a senior engineer whose single most useful framing was: "The code being real doesn't mean it's ready. Ready means it survives someone who isn't you." v3 is that answer: the personal data, personal tools, and machine-specific paths were deliberately removed so the package survives a stranger's machine.