OpenCode Memory Kit

Reusable durable-memory workflow for OpenCode projects.

This kit gives you two things:

• global OpenCode commands and agents for durable memory
• a lightweight bootstrap that installs per-project memory scaffolding

Goals:

• keep long-term project context inside each repo
• keep global OpenCode setup small and reusable
• avoid saturating model context with old session noise
• keep the main thread thin by leaning on OpenCode's built-in explore and general subagents

What gets installed

Global commands and agents:

• /sync-memory [scope]
• /remember-feature <slug>
• /recall-feature <query>
• /review-memory <scope>
• memory-curator
• memory-recall

Project bootstrap files:

• AGENTS.md
• docs/ai-memory/INDEX.md
• docs/ai-memory/product-vision.md
• docs/ai-memory/decisions.md
• docs/ai-memory/troubleshooting.md
• docs/ai-memory/features/README.md

Installed maintenance scripts:

• doctor.ps1 / doctor.sh - read-only installation and project-memory checks
• install-manifest.tsv - hashes of files owned by the kit

/sync-memory is the default checkpoint. It decides between a focused feature update, a broader drift review, or no durable memory update.

Quick start

Recommended setup: use the default OpenCode directories. Do not override OPENCODE_CONFIG_DIR for normal usage.

Install once from the public repo:

PowerShell:

powershell -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/alejodevelop/opencode-memory-kit/main/install.ps1 -UseBasicParsing | iex"

Unix shell:

curl -fsSL https://raw.githubusercontent.com/alejodevelop/opencode-memory-kit/main/install.sh | sh

Bootstrap each repo:

PowerShell:

powershell -ExecutionPolicy Bypass -File "$HOME\.config\opencode\opencode-memory-kit\scripts\bootstrap-project.ps1" -Target .

Unix shell:

sh "$HOME/.config/opencode/opencode-memory-kit/scripts/bootstrap-project.sh" .

If the repo already has AGENTS.md, bootstrap only refreshes or appends the managed block between:

• <!-- opencode-memory-kit:start -->
• <!-- opencode-memory-kit:end -->

That preserves existing project-specific rules outside the managed block.

Run the read-only doctor after bootstrap or upgrade:

powershell -ExecutionPolicy Bypass -File "$HOME\.config\opencode\opencode-memory-kit\scripts\doctor.ps1" -Target .

sh "$HOME/.config/opencode/opencode-memory-kit/scripts/doctor.sh" .

Daily use

1. Work normally with plan and build.
2. Let OpenCode use explore for broad reading and general for multi-step execution.
3. After accepted work when durable repo truth changed, run /sync-memory [scope].
4. In later sessions, run /recall-feature <query>.
5. Use /remember-feature <slug> to force a focused feature-note refresh.
6. Use /review-memory [scope] after broad refactors, removals, or cleanup.

If the repo uses OpenSpec or another spec workflow, the active spec remains the source of truth for requirements, planning, task tracking, and acceptance criteria. After each spec archive for accepted work, run /sync-memory [scope] or say explicitly that no durable memory update is needed.

Typical commands:

/sync-memory auth-flow
/sync-memory
/remember-feature billing-webhook
/recall-feature auth
/recall-feature "TypeError fetch failed"
/review-memory "remove legacy billing"

Upgrade

Update the installed kit:

PowerShell:

$script = (iwr "https://raw.githubusercontent.com/alejodevelop/opencode-memory-kit/main/install.ps1" -UseBasicParsing).Content
& ([scriptblock]::Create($script)) -Force

Unix shell:

curl -fsSL https://raw.githubusercontent.com/alejodevelop/opencode-memory-kit/main/install.sh | sh -s -- --force

Then rerun bootstrap inside the repo:

PowerShell:

powershell -ExecutionPolicy Bypass -File "$HOME\.config\opencode\opencode-memory-kit\scripts\bootstrap-project.ps1" -Target .

Unix shell:

sh "$HOME/.config/opencode/opencode-memory-kit/scripts/bootstrap-project.sh" .

Safe rerun behavior:

• refreshes the managed block in AGENTS.md
• creates missing scaffold files under docs/ai-memory/
• preserves existing saved notes and feature memory files
• never overwrites existing project memory, including with deprecated bootstrap -Force or --force
• upgrades only files recorded as kit-owned and unchanged since installation
• rejects collisions and locally modified managed files instead of overwriting them

Repo layout

agents/                  Global OpenCode agents
commands/                Global OpenCode commands
templates/project/       Files copied into each target repo
scripts/                 Install and bootstrap scripts
tests/                   Cross-platform script checks
legacy-manifest.tsv      Exact hashes eligible for safe pre-manifest adoption

Advanced usage

Install from a local clone while developing the kit:

PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\install-global.ps1

Unix shell:

sh ./scripts/install-global.sh

OPENCODE_CONFIG_DIR is useful for development and testing, but it is not the recommended day-to-day setup. Explicit -ConfigDir / --config-dir wins over that environment variable.

After changing or reinstalling OpenCode commands or agents, quit and restart OpenCode. Running sessions retain their loaded configuration.