opencode-memfs

Git-backed, two-tier hot/cold memory plugin for OpenCode. Gives your agent persistent memory across sessions with automatic git versioning.

How It Works

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 via memory_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.

Installation

Add to your OpenCode config (~/.config/opencode/opencode.json):

{
  "plugin": ["opencode-memfs"]
}

Restart OpenCode and you're ready to go.

Directory Structure

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.

Configuration

Optional. Create ~/.config/opencode/memfs.json:

{
  "hotDir": "system",
  "defaultLimit": 5000,
  "autoCommitDebounceMs": 2000,
  "maxTreeDepth": 3
}

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 |

Tools

The plugin registers 9 custom tools. The agent uses these instead of standard file tools to interact with memory.

Content Tools

memory_read

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.

memory_write

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.

memory_edit

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.

memory_delete

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.

Hierarchy Tools

memory_promote

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 |

memory_demote

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 |

Git / Navigation Tools

memory_tree

Show the memory tree with descriptions and character counts.

| Arg | Type | Default | Description | |---|---|---|---| | scope | "all" | "project" | "global" | "all" | Filter by scope |

memory_history

Show git history of memory changes.

| Arg | Type | Default | Description | |---|---|---|---| | limit | number | 10 | Maximum commits to return |

memory_rollback

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 |

Frontmatter

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 — When true, the agent cannot modify or delete the file. Default: false.

System Prompt

The plugin injects a <memfs> block into the system prompt containing:

1. A tree listing of all files with paths, char counts, and descriptions
2. Instructions on how to use the memory tools
3. 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>

Architecture

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.md tracks all known projects for cross-project awareness

Development

npm run build          # Compile to dist/
npm run dev            # Watch mode
npm run clean          # Remove dist/
npx tsc --noEmit       # Type-check without emitting

License

MIT