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:

1. Agent Efficiency & Zero-Shot Accuracy

• 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."

2. Architectural Consistency (The "Deep Memory")

• 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. Absolute Project Isolation (No "Cross-Talk")

• 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/<hash_A>. 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

Option A: Install from npm (Recommended)

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):

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

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

Option B: Local Development Install

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

1. Clone this repository:

   git clone https://github.com/drpr/alex.git
   cd alex/opencode-max

2. Install dependencies:

   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:

{
  "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).

{
  "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
}

Configuration fields

| 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/[email protected]. Prefer installing via the npm package name to avoid loading stale local path versions.

Isolation Model

• Project isolation: vectors live under .opencode/vectors/<projectId>, 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

npm install

Publish

npm publish --access public

License

MIT