opencode-max

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)

• Ensure you have the OpenCode CLI installed.
• 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"
  ]
}

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

• Clone this repository:

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

• Install dependencies:

  npm install
  

• Build the plugin (if applicable) or ensure plugin.mjs is ready.
• 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

• Install the plugin and complete configuration
• First run builds the initial index (if missing, the plugin will auto-create the codebase table)
• Retrieval is scoped by session and project automatically
• 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/<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