oc-mnemoria

Persistent shared memory for OpenCode agents, powered by mnemoria.

Support this project

If this project has been helpful to you, you are welcome to sponsor it. Sponsorship helps me spend more time maintaining it, fixing bugs, and building new features.

No pressure at all - starring the repo, sharing it, or giving feedback also means a lot.

Become a sponsor

What it does

Every time you start a new OpenCode session, your AI assistant loses all context from previous conversations. oc-mnemoria fixes this by giving all agents a shared "hive mind" — a single persistent memory store where every agent can read and write.

Each memory entry is tagged with the agent that created it (plan, build, ask, review, ...) so any agent can tell who recorded what. The build agent can see what the plan agent decided; the review agent can recall bugs the build agent fixed. No context is lost between roles.

Memories are stored locally in an append-only binary file using mnemoria — a Rust engine with hybrid BM25 + semantic search, CRC32 checksum chains, and corruption recovery.

Prerequisites

• Rust toolchain (to install the mnemoria CLI)
• OpenCode (v0.1+)
• Node.js >= 18

Installation

Run the install script in your project directory:

curl -fsSL https://raw.githubusercontent.com/one-bit/oc-mnemoria/main/install.sh | sh

The script:

1. Installs the mnemoria CLI (via cargo install if needed)
2. Adds "oc-mnemoria" to the plugin array in opencode.json
3. Installs /mn-* slash commands to .opencode/commands/

After installation, restart OpenCode and run:

/mn-stats

You should see memory store statistics (entry count, file size, timestamps).

How it works

Storage layout

All agents share a single memory store:

.opencode/mnemoria/
  log.bin           # append-only binary log
  manifest.json     # metadata and checksums
  mnemoria.lock     # advisory file lock

You can interact with the store directly using the mnemoria CLI:

mnemoria --path .opencode stats
mnemoria --path .opencode search "authentication"
mnemoria --path .opencode export memories.json

Agent tagging

Every memory entry is tagged with the agent that created it via mnemoria's native --agent flag. The agent name is a first-class field on each entry, visible in search results, timeline output, and JSON exports.

# Search only the build agent's memories
mnemoria --path .opencode search -a build "authentication"

# Show only the plan agent's timeline
mnemoria --path .opencode timeline -a plan

Intent capture

The plugin automatically extracts user intents from chat messages via the chat.message hook. When a user describes a goal or task, the plugin categorizes it (e.g. fix, refactor, feature) and stores it in the shared memory, tagged with the current agent. Duplicate intents within the same session are deduplicated.

Agents can also store memories explicitly using the remember tool for discoveries, decisions, solutions, and other observations worth preserving.

System prompt injection

At the start of each session, the plugin injects cross-agent context into the system prompt via the experimental.chat.system.transform hook:

• Memory guidance — instructions for when to use search_memory, ask_memory, and remember
• Recent context — the latest memories from the shared store, each showing which agent created it
• Relevant memories — search results matched against the current user intent (if one exists)
• Past user goals — intents from previous sessions so the agent understands prior work

Tools

Tool	Description
remember	Store a categorized observation in shared memory
search_memory	Search by keyword/semantic similarity
ask_memory	Ask a natural language question
memory_stats	View statistics for the shared store
timeline	Browse memories chronologically (all agents)
forget	Mark a memory as obsolete (append-only tombstone)
compact	Remove forgotten entries/markers and optionally prune old data

Entry types

Observations are categorized when stored:

intent discovery decision problem solution pattern warning success refactor bugfix feature

Slash commands

Command	Description
/mn-ask <q>	Ask about past decisions
/mn-search <q>	Search memories
/mn-stats	Show memory statistics
/mn-recent	Show recent memories
/mn-timeline	Chronological view
/mn-forget ...	Mark a memory as forgotten/obsolete
/mn-compact	Compact store by removing forgotten data

Inspecting memories from the command line

You can use the mnemoria CLI directly to browse, search, and manage the memory store outside of OpenCode. All commands use --path .opencode to point at your project's store (mnemoria auto-appends mnemoria/ to resolve the actual data directory).

Browse the timeline

# Most recent 20 entries (newest first)
mnemoria --path .opencode timeline -r

# Last 5 entries
mnemoria --path .opencode timeline -r -l 5

# Only entries from the build agent
mnemoria --path .opencode timeline -a build

# Entries from a specific time range (Unix ms timestamps)
mnemoria --path .opencode timeline -s 1700000000000 -u 1700100000000

Output looks like:

Timeline (3 entries):
1. [discovery] (build) Found async pattern in auth module - 1700000100000
2. [decision] (plan) Use JWT for session tokens - 1700000050000
3. [intent] (plan) Fix authentication flow - 1700000000000

Search memories

# Keyword + semantic hybrid search
mnemoria --path .opencode search "authentication"

# Limit results
mnemoria --path .opencode search "error handling" -l 5

# Search only one agent's memories
mnemoria --path .opencode search -a review "security"

Ask a question

# Ask a natural language question against the memory store
mnemoria --path .opencode ask "What decisions were made about the database schema?"

# Scoped to a single agent
mnemoria --path .opencode ask -a plan "What was the original plan for auth?"

View statistics

mnemoria --path .opencode stats

Memory Statistics:
  Total entries: 42
  File size: 4096 bytes
  Oldest entry: 1700000000000
  Newest entry: 1700001000000

Export to JSON

mnemoria --path .opencode export memories.json

This produces a JSON array with full entry data including agent_name, entry_type, summary, content, timestamp, and checksum fields. Useful for scripting, analysis, or migrating data.

Add a memory manually

mnemoria --path .opencode add \
  -a build \
  -t decision \
  -s "Switched from REST to GraphQL" \
  "After benchmarking, GraphQL reduced payload size by 60%"

The -t flag accepts any entry type: intent, discovery, decision, problem, solution, pattern, warning, success, refactor, bugfix, feature. Defaults to discovery if omitted.

Verify store integrity

mnemoria --path .opencode verify

Checks the CRC32 checksum chain across all entries. Returns a non-zero exit code on corruption, making it suitable for CI or pre-commit hooks.

Memory maintenance workflows

Over time, some memories become outdated. oc-mnemoria supports a two-step maintenance flow:

1. Mark obsolete entries with forget (append-only marker)
2. Run compact to physically rebuild the store without forgotten entries

In OpenCode (recommended)

Use slash commands:

/mn-search flaky test timeout
/mn-forget id=8d9f... reason="Superseded by retry policy"
/mn-compact

Optionally prune old entries during compaction:

/mn-compact 90

(90 means maxAgeDays=90)

What each step does

• forget keeps history intact by writing a tombstone marker
• compact removes forgotten markers/entries and optionally old data
• This keeps the memory store accurate while preserving auditability between runs

Git integration

Mnemoria's append-only binary format is designed for version control. You can commit the memory store to track history alongside your code:

git add .opencode/
git commit -m "update agent memories"

Or ignore it:

echo ".opencode/mnemoria/" >> .gitignore  # ignore just the memory store

FAQ

How much disk space does this use? The store starts empty. A typical entry is ~100-500 bytes. Active daily use produces roughly 2-10 MB per year.

Is my data sent anywhere? No. Everything stays on your local filesystem. The mnemoria engine runs entirely offline.

How fast is it? The mnemoria Rust engine delivers sub-millisecond search latency for typical store sizes (<10k entries). The plugin shells out to the CLI, so there's ~50ms overhead per operation from process spawning.

Can I reset the memory? Delete the store directory:

rm -rf .opencode/mnemoria/

Can I search only one agent's memories? Yes. Pass the agent parameter to search_memory, ask_memory, or timeline. From the CLI: mnemoria --path .opencode search -a build "auth".

License

MIT