OpenCode Max Plugin

OpenCode Max is the fundamental solution to the "Project Amnesia" problem in AI coding agents. It provides a strictly isolated, local-first memory architecture that guarantees coding efficiency and architectural consistency across long-term projects.

Unlike generic memory plugins that treat context as a flat list, OpenCode Max understands project boundaries and session lifecycles, ensuring your agent never "hallucinates" patterns from other repos or forgets architectural decisions made weeks ago.

The Core Value: Solving Global Memory Fundamentally

Most AI agents suffer from Context Drift: as a project grows, they lose track of established patterns, or worse, bleed context from Project A into Project B. OpenCode Max solves this at the architectural level:

$3

- Problem: Agents often waste tokens re-learning your project structure in every session.
- Solution: With persistent, project-hashed memory, OpenCode Max instantly provides the exact relevant context (types, utils, patterns) before the agent writes a single line. This drastically reduces "correction loops" and makes the agent "get it right the first time."

$3

- Problem: "Why did you use var here? We switched to const last week!" Agents forget past decisions.
- Solution: By retrieving historical context scoped strictly to the current project, the agent maintains consistent coding styles, variable naming conventions, and architectural patterns throughout the project's lifecycle—whether it's Day 1 or Day 100.

$3

- Problem: Working on a Rust backend in the morning and a React frontend in the afternoon often confuses agents, leading to "hallucinated" imports or syntax.
- Solution: Hard Directory Hashing. Vectors for Project A are physically stored in .opencode/vectors/. It is mathematically impossible for the agent to access Project B's context while working on Project A. This is not just a filter; it's a physical firewall for your context.

---

Why OpenCode Max: The Definitive Comparison

While plugins like opencode-supermemory or opencode-mem offer memory, they often rely on cloud services or loose tagging. OpenCode Max is built for Enterprise-Grade Consistency.

| Feature | OpenCode Max | Cloud Memory Plugins | Generic Local Plugins |
| :--- | :--- | :--- | :--- |
| Global Memory Problem | SOLVED (Physical Isolation) | Mitigated (Tags/Filters) | Unsolved (Flat File) |
| Agent Consistency | High (Project-Scoped RAG) | Medium (Global Context Noise) | Low (Session Only) |
| Coding Efficiency | High (Precise Retrieval) | Medium (Network Latency) | Low (Limited Context) |
| Data Privacy | 100% Local (LanceDB) | Cloud Dependent | Local |
| Indexing Strategy | Incremental & Background | Full Re-upload | Manual / Sync |

Verdict: If you need an agent that "codes like a senior engineer" who remembers the project history without getting confused by other projects, OpenCode Max is the only architectural solution.

---

Core Features

- Task tracking and synchronization
- Memory indexing and retrieval with LanceDB
- Project‑level vector isolation via hashed project root
- Session‑level retrieval filters for tasks and history
- Incremental background indexing

Requirements

- OpenCode CLI 1.1.37 (or later)
- Node.js 18+

Installation

$3

1. Ensure you have the OpenCode CLI installed.
2. Edit your OpenCode configuration file (usually ~/.config/opencode/config.json or %USERPROFILE%\\.config\\opencode\\config.json):

``json
{
"$schema": "https://opencode.ai/config.json",
"plugin": [
"opencode-max"
]
}
`

3. Restart your OpenCode session. The plugin will be automatically downloaded and installed.

$3

If you want to modify the plugin or use a local version:

1. Clone this repository:
`bash
git clone https://github.com/drpr/alex.git
cd alex/opencode-max
`
2. Install dependencies:
`bash
npm install
`
3. Build the plugin (if applicable) or ensure plugin.mjs is ready.
4. Point your OpenCode config to the absolute path of the opencode-max directory:

`json
{
"plugin": [
"/Users/yourname/path/to/alex/opencode-max"
]
}
`

Configuration

To customize indexing behavior, create a .opencode-max.json file in the root of the project you are working on (not the plugin directory).

`json
{
"vectorDir": ".opencode/vectors",
"include": ["*/.{js,ts,jsx,tsx,py,java,cs,go,rs,md,c,cpp,h}"],
"exclude": ["/node_modules/", "/dist/", "/.git/", "/.vscode/"],
"topK": 8,
"indexingDebounce": 1000
}
`

$3

| Field | Meaning | Recommendation |
| --- | --- | --- |
| vectorDir | Vector storage directory | Keep default |
| include | File patterns to index | Cover primary languages |
| exclude | File patterns to ignore | Exclude build outputs and dependencies |
| topK | Max candidates per retrieval | 3–8 |

Usage

1. Install the plugin and complete configuration
2. First run builds the initial index (if missing, the plugin will auto-create the codebase table)
3. Retrieval is scoped by session and project automatically
4. Switching projects requires no manual cleanup because isolation is enforced

Troubleshooting

- Bun Error Overlay (macOS)
Use polling-based file watching instead of native fsevents (built-in). If the overlay persists, restart OpenCode and retry.
- First retrieval returns “Table 'codebase' was not found”
The plugin auto-detects and creates the codebase table. Wait for the initial indexing to complete.
- Version alignment
Ensure your host CLI and plugin interface align to @opencode-ai/plugin@1.1.37. Prefer installing via the npm package name to avoid loading stale local path versions.

Isolation Model

- Project isolation: vectors live under .opencode/vectors/, derived from a hash of the project root
- Session isolation: task and history retrieval are filtered by session ID

Landscape and References

OpenCode Max is designed for developers who demand absolute context control.

References:
- OpenCode plugin docs: https://opencode.ai/docs/plugins/
- Community plugin directory: https://github.com/awesome-opencode/awesome-opencode
- Find this plugin:
- npm: https://www.npmjs.com/package/opencode-max
- GitHub: https://github.com/drpr/alex/tree/main/opencode-max
- In the community directory, search for “opencode-max” to locate the listing

Development

`bash
npm install
`

Publish

`bash
npm publish --access public
``

License

MIT