Git-backed, two-tier hot/cold memory plugin for OpenCode. Gives your agent persistent memory across sessions with automatic git versioning.
Memory files are plain markdown with YAML frontmatter, organized into two tiers:
- Hot (
system/) — Full content is pinned in the system prompt every turn. Use for high-signal, always-relevant context (persona, user prefs, project conventions). - Cold (
reference/,archive/, etc.) — Only the path and description appear in a tree listing. The agent reads cold files on demand viamemory_read. Use for reference material, debugging notes, historical context.
All changes are automatically committed to a local git repo via a filesystem watcher (2s debounce). The agent can browse history and roll back with memory_history / memory_rollback.
Add to your OpenCode config (~/.config/opencode/opencode.json):
{
"plugin": ["opencode-memfs"]
}Restart OpenCode and you're ready to go.
All memory is centralized under ~/.config/opencode/memory/ in a single git repo:
~/.config/opencode/memory/ # Single git repo, single watcher
├── global/ # Shared across all projects
│ ├── system/ # HOT — pinned in system prompt
│ │ ├── persona.md # Agent identity and behavior
│ │ ├── human.md # User preferences and habits
│ │ └── projects.md # Auto-maintained project registry (readonly)
│ └── reference/ # COLD — read on demand
└── projects/
├── my-app/ # Per-project memory
│ ├── system/
│ │ └── project.md # Build commands, architecture, conventions
│ ├── reference/ # COLD — read on demand
│ └── archive/ # COLD — historical context
└── another-project/
├── system/
│ └── project.md
├── reference/
└── archive/
Project directories are named by the project's directory basename (e.g. my-app from /home/user/projects/my-app). If two projects share the same basename, a short hash suffix is appended to disambiguate (e.g. my-app-a3f2).
The projects.md file is an auto-maintained registry of all known projects — updated on each plugin init with the project name, path, and last-seen date.
Optional. Create ~/.config/opencode/memfs.json:
{
"hotDir": "system",
"defaultLimit": 5000,
"autoCommitDebounceMs": 2000,
"maxTreeDepth": 3,
"cacheTtl": "5m",
"refreshThresholdPercentage": 65,
"refreshOnPromoteDemote": true
}All fields are optional with sensible defaults:
| Field | Type | Default | Description |
|---|---|---|---|
hotDir |
string | "system" |
Directory name for hot (pinned) files |
defaultLimit |
number | 5000 |
Default character limit for new files |
autoCommitDebounceMs |
number | 2000 |
Debounce delay (ms) before auto-committing |
maxTreeDepth |
number | 3 |
Maximum directory depth in tree listing |
cacheTtl |
string | number | "5m" |
Injection-cache sync point ("5m", "30s", "500ms", or ms number) |
refreshThresholdPercentage |
number | 65 |
Context-usage % at which pressure forces a refresh |
refreshOnPromoteDemote |
boolean | true |
Whether memory_promote/memory_demote force-bust the cache |
The plugin registers 10 custom tools. The agent uses these instead of standard file tools to interact with memory.
Read a memory file with metadata.
| Arg | Type | Description |
|---|---|---|
path |
string | Relative path (e.g. "system/persona.md") |
scope |
"project" | "global" |
Memory scope to target |
Returns path, description, char count, limit, readonly status, and full content.
Create or fully replace a memory file.
| Arg | Type | Required | Description |
|---|---|---|---|
path |
string | yes | Relative path |
scope |
"project" | "global" |
yes | Memory scope to target |
content |
string | yes | Full content body |
description |
string | no | File description (auto-generated from filename if omitted) |
limit |
number | no | Character limit (defaults to defaultLimit) |
readonly |
boolean | no | Protect from modification (defaults to false) |
Validates that content doesn't exceed the limit and that existing readonly files aren't overwritten.
Partial edit using exact string replacement.
| Arg | Type | Description |
|---|---|---|
path |
string | Relative path |
scope |
"project" | "global" |
Memory scope to target |
oldString |
string | Exact string to find |
newString |
string | Replacement string |
Same semantics as the core Edit tool. Validates readonly status and char limit.
Remove a memory file.
| Arg | Type | Description |
|---|---|---|
path |
string | Relative path |
scope |
"project" | "global" |
Memory scope to target |
Validates that the file exists and is not readonly.
Move a cold file into system/ (make it hot). The file will be pinned in the system prompt.
| Arg | Type | Description |
|---|---|---|
path |
string | Relative path to the cold file |
scope |
"project" | "global" |
Memory scope to target |
Move a hot file from system/ into reference/ (make it cold). The file will only appear as a tree entry.
| Arg | Type | Description |
|---|---|---|
path |
string | Relative path to the hot file |
scope |
"project" | "global" |
Memory scope to target |
Show the memory tree with descriptions and character counts.
| Arg | Type | Default | Description |
|---|---|---|---|
scope |
"all" | "project" | "global" |
"all" |
Filter by scope |
Show git history of memory changes.
| Arg | Type | Default | Description |
|---|---|---|---|
limit |
number | 10 |
Maximum commits to return |
Revert memory to a specific commit. Creates a new commit recording the rollback (history is preserved).
| Arg | Type | Description |
|---|---|---|
commitHash |
string | Commit hash from memory_history |
Force the injected <memfs> system-prompt block to refresh on the next turn, regardless of the injection cache's TTL/pressure state.
No arguments.
Use sparingly — the cache exists to preserve upstream prompt-cache prefix hits. Flush when a recent memory write must be visible in the system prompt immediately (e.g. before handing off to a sub-agent). The /memfs-flush command does the same thing.
Every memory file uses YAML frontmatter:
---
description: "What this file contains and when to reference it"
limit: 5000
readonly: false
---
Your content here...description— Navigation signal visible in the tree listing. Auto-generated from the filename if omitted.limit— Maximum character count for the body. Default:5000.readonly— Whentrue, the agent cannot modify or delete the file. Default:false.
The plugin injects a <memfs> block into the system prompt containing:
- A tree listing of all files with paths, char counts, and descriptions
- Instructions on how to use the memory tools
- Full content of all hot (
system/) files
<memfs>
<tree scope="global">
system/human.md (128/5000) — User preferences and working style
system/persona.md (342/5000) — Agent identity and behavior guidelines
</tree>
<tree scope="project">
system/project.md (450/5000) — Build commands, architecture, conventions
reference/api-conventions.md (890/5000) — API naming and error handling patterns
</tree>
<instructions>
Your persistent memory is stored as markdown files.
Files in system/ are pinned — you always see their full contents below.
...
</instructions>
<system path="system/human.md" chars="128" limit="5000" scope="global">
...full content...
</system>
<system path="system/project.md" chars="450" limit="5000" scope="project">
...full content...
</system>
</memfs>Every write that modifies the <memfs> block would — without care — change the system prompt and bust the upstream provider's KV-cache prefix (Anthropic, Bedrock, etc.), which costs real money on long sessions. The plugin defers rebuilds of the rendered block until a genuine cache-bust moment.
Two-layer model:
| Layer | When | Why |
|---|---|---|
Disk (~/.config/opencode/memory/**) |
Every tool call, immediately | Crash safety, read-after-write consistency, git-commitable |
Render (the <memfs> block injected into the system prompt) |
Deferred to the next cache-bust moment | Preserves the provider's prompt-cache prefix |
Cache-bust ladder (per session, on each experimental.chat.system.transform):
- No cached entry yet → render (first turn)
- Content hash unchanged → serve cached (fast path, byte-identical)
- A force-bust was requested (
memory_promote/memory_demote/memory_flush//memfs-flush) → render - Context usage ≥
refreshThresholdPercentage→ render (pressure beats freshness) now - lastResponseTime > cacheTtlMs→ render (provider cache likely stale anyway)- Otherwise → serve cached bytes even though content has changed
Rules 3–5 are the three independent ways a bust can fire. Rule 6 is the point: between bust moments, the agent sees identical bytes in the system prompt across many memory edits.
What is never stale:
memory_readalways hits disk → always returns the latest contentmemory_treealways scans live → always current- The only thing that can be stale is the injected
<memfs>block, and only for at most one turn's worth of time (bounded by the ladder)
cacheTtl is a sync point, not a timer. Setting "5m" matches Anthropic's default 5-minute prompt-cache window — it describes "when busting the upstream cache is free anyway," not when a local timer fires. For Anthropic's extended 1-hour cache beta, set "1h".
Every decision is logged to ~/.config/opencode/memfs.log (one line per transform). Tail it during a session to see exactly which ladder branch fired:
tail -f ~/.config/opencode/memfs.logExample:
2026-04-20T13:42:01.123Z INFO plugin loaded projectName=opencode-memfs cache_ttl_ms=300000 refresh_threshold_pct=65
2026-04-20T13:42:01.456Z INFO refreshed <memfs> render reason=first session=ses_01... chars=2812 prev_cache_age_ms=0 since_last_response_ms=0 ttl_ms=300000 usage_pct=0
2026-04-20T13:42:09.789Z INFO served cached <memfs> session=ses_01... hash_match=true cache_age_ms=8333 since_last_response_ms=8333 ttl_ms=300000 usage_pct=12.4 chars=2812
2026-04-20T13:48:15.012Z INFO refreshed <memfs> render reason=ttl session=ses_01... chars=2856 prev_cache_age_ms=374223 since_last_response_ms=374223 ttl_ms=300000 usage_pct=18.1
Key fields:
hash_match=trueon a served-cached line means a fresh render would be byte-identical — serving cached is the optimization working correctly (and TTL doesn't fire in this case, because rebuilding produces the same bytes).hash_match=false+ served-cached means deferred bust — the content changed but none of force/pressure/TTL triggers applied yet.reason=forced:<source>identifies which tool drove a force-bust (promote,demote,flush-tool,flush-command).
Agent calls memory_write / memory_edit / etc.
→ Tool validates input (readonly, limit, existence)
→ Atomic write to disk (tmp + rename)
→ Tool returns result immediately
→ Single fs.watch on ~/.config/opencode/memory/ detects change
→ 2-second debounce (batches rapid edits)
→ git add . && git commit -m "memory: update <files>"
Key design decisions:
- Centralized storage — All memory under
~/.config/opencode/memory/with one git repo and one watcher - Tool isolation — Dedicated memory tools prevent ambiguity between "editing code" and "updating memory"
- Progressive disclosure — Tree is always visible (cheap), content loaded on demand (expensive)
- Git versioning — Rollback, audit trail, and conflict resolution without custom code
- Decoupled commit path — Tools write files, watcher handles git. Catches all changes regardless of source
- Atomic writes — tmp + rename prevents corruption from partial writes
- Projects registry — Auto-maintained
projects.mdtracks all known projects for cross-project awareness - Injection cache — Rendered
<memfs>block is cached per session and only rebuilt at genuine cache-bust moments (see above), preserving upstream prompt-cache prefix hits across many memory edits
npm run build # Compile to dist/
npm run dev # Watch mode
npm run clean # Remove dist/
npx tsc --noEmit # Type-check without emittingMIT