opencode-localmemory

Persistent local memory plugin for OpenCode — no subscription, no external service, zero cost.

Stores memories as Markdown files with YAML frontmatter organized per-project under ~/.config/opencode/localmemory/. Inspired by Claude Code's memory system, but 100% local and offline.

Installation

From npm (recommended)

Add to your opencode.json or ~/.config/opencode/opencode.jsonc:

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

OpenCode will install it automatically at startup via Bun.

From source

git clone https://github.com/DevairRestani/memmoryit.git
cd memmoryit
bun install
bun run build
bun run install-plugin

Or manually add to ~/.config/opencode/opencode.jsonc:

{
  "plugin": ["file:///absolute/path/to/memmoryit"]
}

Restart OpenCode and the memory tool will appear in the available tools list.

How it works

The memory tool

The agent gets direct access to a memory tool with 7 modes:

| Mode | Arguments | Description | |------|-----------|-------------| | save | name, content, scope?, type?, tags? | Create or update a memory | | search | query | Search memories by keywords | | list | scope? | List all memories in a scope | | forget | name | Remove a memory by name | | recall | query | Get top relevant memories with freshness warnings | | extract | — | Get instructions for extracting memories from conversation | | consolidate | — | Get instructions for reviewing, merging, and pruning memories |

Scopes

| Scope | Storage | Availability | |-------|---------|-------------| | user | ~/.config/opencode/localmemory/user/memory/ | Cross-project, always available | | project | ~/.config/opencode/localmemory/projects/<hash>/memory/ | Isolated per git repository |

The project hash is derived from git rev-parse --show-toplevel.

Memory types (4 types)

| Type | What it stores | Example | |------|---------------|---------| | user | Role, goals, preferences, knowledge level | "User is a senior backend engineer" | | feedback | Corrections about how to work with this user | "Always run tests after changes" | | project | Work context not derivable from code | "Deploy deadline is April 15" | | reference | Pointers to external systems | "Monitoring: https://grafana.example.com/d/abc" |

File format

Each memory is a .md file with YAML frontmatter:

---
name: User Role
description: Senior backend engineer focused on observability
type: user
created: 2026-04-02T10:00:00Z
updated: 2026-04-02T10:00:00Z
tags: [observability, python]
---

Content of the memory goes here.

MEMORY.md index

A MEMORY.md index file is automatically maintained in each scope directory and loaded into the system prompt so the agent always knows what memories exist. Limits: 200 lines, 25KB, ~150 chars per entry.

Context compaction

When the context window fills up, the experimental.session.compacting hook injects all memories into the continuation prompt so nothing is lost across compactions.

Search

Keyword-based token overlap with recency scoring — no embeddings, no external API. Works fully offline.

Usage

Phrases that trigger automatic saving

The agent recognizes phrases like:

• "remember that I prefer concise responses"
• "save that this project uses Bun, not Node"
• "don't forget: deploy is via GitHub Actions"
• "lembra que prefiro respostas concisas"
• "salva isso"
• "não esqueça"

Direct tool usage

Save to project memory: this project uses Vue 3 with Composition API.

Search memory for what you know about this project's deployment.

Storage layout

~/.config/opencode/localmemory/
├── user/
│   └── memory/
│       ├── MEMORY.md           # Index file (always in system prompt)
│       ├── user_role.md        # Memory files with frontmatter
│       └── ...
└── projects/
    └── <sha256-hash>/
        └── memory/
            ├── MEMORY.md
            ├── project_context.md
            └── ...

Legacy .json files from v1 are auto-migrated to .md on first load (originals backed up as .json.bak).

Comparison with opencode-supermemory

| Feature | opencode-supermemory | opencode-localmemory | |---------|---------------------|---------------------| | Storage | Cloud (Supermemory API) | Local (~/.config/...) | | Semantic search | Vector embeddings | Keyword overlap | | Cost | Paid subscription | Zero | | Privacy | Data sent to API | 100% local | | Cross-machine sync | Yes (via API) | No (portable via files) | | Works offline | No | Yes |

Development

bun install
bun run build        # Compile to dist/
bun run typecheck    # Type-check only
bun run dev          # Watch mode
bun test             # Run tests

License

MIT