OpenCode Memory

Deciding where to store information depends on its stability and scope:

OpenCode Memory provides two ways to manage long-term context:

1. Auto-capture (Enabled by default via autoCaptureEnabled: true): This runs automatically after conversation turns when the session goes idle. A background AI request summarizes technical work and saves it as memory. This requires an AI provider capable of returning structured/tool-call output (e.g., opencodeProvider).
2. Manual Memory: You can use the memory tool on demand to perform specific actions. Manual operations like search, add, list, and forget work even if auto-capture is not configured.

Note: Auto-capture and User Profile learning specifically require a provider that supports tool-calling/structured output.

// Manual usage example
memory({ mode: "add", content: "Project uses microservices architecture" });

To prevent unauthorized access to the local HTTP API, opencode-mem requires an authentication token for every /api/* request.

1. Locate the token: The token is a random 256-bit string generated on the first run and stored in ~/.opencode-mem/.auth-token (with 0600 permissions).
2. Include the token in requests: When making manual API calls (e.g., via curl or other local processes), you must include the token in the x-opencode-mem-token header.

Note: The bundled web UI handles this automatically by reading the token from window.__OPENCODE_MEM_TOKEN__ injected into the server-rendered index.html.

# Example curl request with authentication
curl -X POST http://localhost:PORT/api/memories \
  -H "x-opencode-mem-token: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"content":"example memory"}'

When upgrading to a version of opencode-mem that uses native Turso/libSQL vector formats, the plugin performs an automatic migration on the first startup:

• Shards are backed up as <shard>.db.legacy.bak.
• Progress is tracked in <shard>.db.turso-migrate.json.
• A global .turso-migrated marker is written upon success.
• A lock file (.turso-migrate.lock) prevents multiple OpenCode instances from running migrations simultaneously.

Important: Do not run multiple OpenCode instances against the same storagePath during migration. If a migration is interrupted, the next startup will resume from the backup automatically.

You can browse the memory–prompt timeline, inspect captures, and manage your user profile via the built-in web interface at http://127.0.0.1:4747.

Security Note: By default, the server binds to 127.0.0.1. If you change webServerHost to 0.0.0.0 or another non-loopback host, you must set a webServerApiToken. All /api/* requests will then require an Authorization: Bearer <token> or X-Opencode-Mem-Token header. You can access the UI with the token in the URL: http://<host>:4747/?apiToken=<token>.

By default, opencode-mem identifies a project by its enclosing git repository, creating isolated stores for each repo. To share a single memory store across a multi-repo workspace (like a monorepo or a repo managed tree), place an empty marker file named .opencode-mem-project at the workspace root.

Every session started anywhere underneath this marker will resolve to that root and share the same memory store. The marker takes precedence over git detection.

touch ~/my-workspace/.opencode-mem-project

To install the plugin, add opencode-mem to the plugin array in your OpenCode configuration file located at ~/.config/opencode/opencode.json.

Windows Users: The configuration file must be placed at %USERPROFILE%\.config\opencode\opencode.json (e.g., C:\Users\<you>\.config\opencode\opencode.json). The plugin does not use %APPDATA% or %LOCALAPPDATA% for its entry. After updating the file, restart OpenCode to trigger the automatic download.

{
  "plugin": ["opencode-mem"],
}

If you are contributing to the project, use the following commands to set up your environment, build the project, and verify the code quality using bun.

bun install
bun run build
bun run typecheck
bun run format

In multi-repo workspaces (like those managed by Google repo or monorepos), you can pin a shared project root by placing a marker file named .opencode-mem-project at the desired workspace root.

When this file is present, opencode-mem will resolve the project identity to that specific directory instead of the individual physical git repository where the code is running. This allows multiple nested repositories to share a single memory store.

# Create the marker file at your workspace root
touch .opencode-mem-project

If webServerHost is set to something other than loopback (e.g., 0.0.0.0), the web UI is accessible on your local network. To secure it, use HTTP Basic Auth in the config file.

• webServerAuthPassword: When set, the server requires credentials. Supports literal strings, env://VAR, or file:///path/to/secret.
• webServerAuthUsername: The username required. Defaults to the current OS user ($USER) if not specified.

{
  "webServerHost": "0.0.0.0",
  "webServerAuthPassword": "pick-a-strong-one",
  "webServerAuthUsername": "admin"
}

Confidence in a user profile entry is a dynamic value calculated via syncConfidence. It is derived from a combination of:

1. Bayesian Alpha/Beta: The ratio of alpha (successes/matches) to beta (failures/non-matches).
2. Temporal Decay: Confidence decays over time based on CONFIG.userProfileConfidenceDecayDays. The decay follows a half-life model that scales with the item's frequency.
3. Recency Trend: A trendMultiplier is applied based on how recently the item was last matched, ensuring that frequently recent behaviors maintain higher confidence than stale ones.