opencode-working-memory/docs/installation.md

Installation Guide

Quick Install

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

{
  "plugin": ["opencode-working-memory"]
}

Restart OpenCode. The plugin activates automatically — no manual setup needed.

Note

: The correct key is plugin (singular), not plugins.

For LLM Agents

1. Edit ~/.config/opencode/opencode.json
2. Add "opencode-working-memory" to the plugin array
3. Verify the config file was saved correctly

Verification

After restarting OpenCode, memory context appears automatically in system prompts. You'll see:

<workspace_memory>
- [decision] ... (if any long-term memories exist)
</workspace_memory>

---
<workspace_memory_candidates>
- [project] ... (candidates for long-term memory)
</workspace_memory_candidates>

Active Files:
- path/to/file.ts (action, count)

Open Errors: (none, or listed)

No tools to call. The plugin works automatically via hooks.

How Memory Works

Workspace Memory (Long-term)

Persists across sessions. Automatically extracted during compaction when you say "remember this" or when important decisions are made.

Hot Session State (Short-term)

Tracks current session:

• Active files (what you're working on)
• Open errors (unresolved issues)
• Recent decisions (for compaction candidate promotion)

Troubleshooting

Plugin Not Loading

Symptom: No memory context in system prompt

Solution:

1. Check ~/.config/opencode/opencode.json uses "plugin" (not "plugins")
2. Restart OpenCode to trigger automatic installation
3. Check OpenCode logs for any download errors

Memory Files Not Created

Symptom: No ~/.local/share/opencode-working-memory/ directory

Solution:

1. Ensure OpenCode has write permissions in home directory
2. Trigger memory operations by working normally (plugin creates files on-demand)
3. Check that plugin is listed in config

Memory Not Persisting

Symptom: Workspace memory empty after restart

Solution:

1. Verify you're in the same workspace (different workspace = different memory)
2. Ensure <workspace_memory_candidates> were captured during compaction
3. Check workspace-memory.json exists

Type Errors During Development

Symptom: TypeScript errors when modifying the plugin source

Solution:

1. Run npm install to install dev dependencies
2. Run npm run typecheck to check for errors
3. Run npm test to verify functionality

Uninstallation

Remove "opencode-working-memory" from the plugin array in ~/.config/opencode/opencode.json.

Memory files in ~/.local/share/opencode-working-memory/ persist unless manually deleted.

Manual Memory Management

View Workspace Memory

cat ~/.local/share/opencode-working-memory/workspaces/*/workspace-memory.json | jq

View Session State

cat ~/.local/share/opencode-working-memory/workspaces/*/sessions/*.json | jq

Clear Workspace Memory

rm ~/.local/share/opencode-working-memory/workspaces/*/workspace-memory.json

Clear All Session States

rm -rf ~/.local/share/opencode-working-memory/workspaces/*/sessions/*.json

Next Steps

• Read Architecture Documentation to understand how the three layers work
• See Configuration Guide for customization options

---

Last Updated: April 2026