@mem9/opencode 0.1.0

package/README.md

@@ -0,0 +1,268 @@
+# OpenCode Plugin for mem9
+
+Persistent memory for [OpenCode](https://opencode.ai).
+
+The package ships two plugin entrypoints:
+
+- a server plugin for recall, auto-ingest, and memory tools
+- a TUI plugin for interactive setup inside OpenCode
+
+## Quick Start
+
+### 1. Install the server plugin
+
+Install the server plugin in one scope only.
+
+User scope:
+
+File: `~/.config/opencode/opencode.json`
+
+```json
+{
+  "plugin": ["@mem9/opencode"]
+}
+```
+
+Project scope:
+
+File: `<project>/.opencode/opencode.json`
+
+```json
+{
+  "plugin": ["@mem9/opencode"]
+}
+```
+
+Recommended pattern:
+
+- install the server plugin once at user scope
+- keep project-specific behavior in `<project>/.opencode/mem9.json`
+
+`@mem9/opencode` resolves npm `latest`.
+If you publish a prerelease channel, install it with an explicit npm specifier instead:
+
+```json
+{
+  "plugin": ["@mem9/opencode@rc"]
+}
+```
+
+You can also pin an exact prerelease version:
+
+```json
+{
+  "plugin": ["@mem9/opencode@0.1.0-rc.0"]
+}
+```
+
+Avoid duplicate plugin loading, such as:
+
+- user scope plugin plus project scope plugin
+- npm plugin plus local file plugin
+
+### 2. Install the TUI plugin for `/mem9-setup`
+
+File: `~/.config/opencode/tui.json`
+
+```json
+{
+  "plugin": ["@mem9/opencode"]
+}
+```
+
+That enables the `/mem9-setup` command inside OpenCode.
+
+### 3. Restart OpenCode and run `/mem9-setup`
+
+`/mem9-setup` is the single entrypoint for both:
+
+- shared mem9 credentials
+- OpenCode user/project mem9 settings
+
+When no usable profile exists, it shows two actions:
+
+- `Get a mem9 API key automatically`
+- `Add an existing mem9 API key`
+
+When usable profiles already exist, it shows four actions:
+
+- `Get a mem9 API key automatically`
+- `Add an existing mem9 API key`
+- `Use an existing mem9 profile in a scope`
+- `Configure user/project settings`
+
+Profile creation ends after the profile is saved. Scope configuration is a separate action.
+
+## File Layout
+
+OpenCode config directory:
+
+- macOS/Linux: usually `~/.config/opencode`
+- Windows: usually `%APPDATA%\\opencode`
+
+OpenCode state directory:
+
+- macOS/Linux: usually `~/.local/share/opencode`
+- Windows: usually `%LOCALAPPDATA%\\opencode`
+
+mem9 uses these files:
+
+- server plugin list: `~/.config/opencode/opencode.json` or `<project>/.opencode/opencode.json`
+- TUI plugin list: `~/.config/opencode/tui.json`
+- shared credentials: `$MEM9_HOME/.credentials.json`
+- user mem9 config: `<OpenCode config dir>/mem9.json`
+- project mem9 config: `<project>/.opencode/mem9.json`
+- debug logs: `<OpenCode state dir>/plugins/mem9/log/YYYY-MM-DD.jsonl`
+
+`MEM9_HOME` defaults to `$HOME/.mem9`.
+
+## Credentials File
+
+Shared credentials live in:
+
+```text
+$MEM9_HOME/.credentials.json
+```
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "default": {
+      "label": "Personal",
+      "baseUrl": "https://api.mem9.ai",
+      "apiKey": "..."
+    }
+  }
+}
+```
+
+`profiles` stores credentials only.
+
+## OpenCode mem9 Config
+
+User and project mem9 config use the same schema:
+
+```json
+{
+  "schemaVersion": 1,
+  "profileId": "default",
+  "debug": false,
+  "defaultTimeoutMs": 8000,
+  "searchTimeoutMs": 15000
+}
+```
+
+Field meanings:
+
+- `profileId`: which shared profile this scope should use
+- `debug`: enable redacted JSONL debug logs
+- `defaultTimeoutMs`: request timeout for normal mem9 calls
+- `searchTimeoutMs`: request timeout for recall search
+
+Project config overrides user config for the current repository.
+
+## Runtime Overrides
+
+These environment variables still override disk config at runtime:
+
+- `MEM9_API_KEY`
+- `MEM9_API_URL`
+- `MEM9_DEBUG`
+- `MEM9_HOME`
+
+Legacy compatibility remains:
+
+- `MEM9_TENANT_ID`
+
+`MEM9_TENANT_ID` is treated as the API key source for older setups.
+
+## Local Development Install
+
+You can also point OpenCode at a local checkout.
+
+Server plugin example:
+
+```json
+{
+  "plugin": ["./.opencode/plugins/mem9/src/index.ts"]
+}
+```
+
+TUI plugin example:
+
+```json
+{
+  "plugin": ["./.opencode/plugins/mem9/src/tui/index.ts"]
+}
+```
+
+Keep the same one-scope rule for the server plugin even when using local paths.
+
+## What the Plugin Does
+
+The server plugin does three things:
+
+- recalls relevant mem9 memories before each chat turn
+- exposes mem9 memory tools inside OpenCode
+- starts best-effort background smart ingest when the session becomes idle and when compaction begins
+
+### Hook Flow
+
+OpenCode integration currently uses four runtime hooks:
+
+| Hook | What mem9 does |
+| --- | --- |
+| `chat.message` | Captures the latest real user prompt and updates in-memory session state. |
+| `experimental.chat.system.transform` | Searches mem9 with the captured prompt and injects a `<relevant-memories>` block. |
+| `event` with `session.idle` | Starts a best-effort background smart-ingest pass for the recent transcript window. |
+| `experimental.session.compacting` | Pushes a compaction hint and starts another best-effort background smart-ingest pass. |
+
+### Recall
+
+The plugin captures the latest real user prompt from `chat.message`, cleans it, bounds it, and injects a formatted recall block during `experimental.chat.system.transform`.
+
+### Auto-ingest
+
+The plugin ingests from two points:
+
+- `session.idle`
+- `experimental.session.compacting`
+
+Both paths fetch up to 24 recent session messages, keep real text-only `user` and `assistant` turns, strip injected memory blocks, and upload the last 12 cleaned messages in the background.
+
+Identical transcripts are deduped per in-memory session state, so a matching idle ingest and compaction ingest share one upload while that session state stays warm.
+
+Two timing details matter:
+
+- hook completion happens before the background upload finishes
+- the dedupe window is in-memory and TTL-bound to about 15 minutes, so restart or cache expiry can upload the same transcript again
+
+### Tools
+
+The plugin registers these tools:
+
+- `memory_store`
+- `memory_search`
+- `memory_get`
+- `memory_update`
+- `memory_delete`
+
+## Troubleshooting
+
+- `Setup pending` means the plugin could not find a usable runtime identity. Run `/mem9-setup`, add `MEM9_API_KEY`, or point the active `mem9.json` scope at a profile with a non-empty `apiKey`.
+- If `/mem9-setup` is missing, confirm `@mem9/opencode` is listed in `~/.config/opencode/tui.json`.
+- If recall or tools work in one project and not another, check whether the project has its own `.opencode/mem9.json` override.
+- If recall, auto-ingest, or debug logs appear to run twice, check for duplicate plugin registration across user scope, project scope, npm, or local file paths.
+- If the selected profile exists but has no `apiKey`, update that profile in `$MEM9_HOME/.credentials.json`.
+- If debug logging is enabled and no file appears, confirm OpenCode can write to its state directory.
+
+## Local Verification
+
+```bash
+pnpm test
+pnpm run typecheck
+pnpm run pack:check
+```

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mem9/opencode",
+  "version": "0.1.0",
+  "description": "OpenCode memory plugin — cloud-persistent AI agent memory with hybrid vector + keyword search via mem9",
+  "type": "module",
+  "main": "src/index.ts",
+  "oc-plugin": [
+    "server",
+    "tui"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/tui/index.ts"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "mem9-ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mem9-ai/mem9.git",
+    "directory": "opencode-plugin"
+  },
+  "homepage": "https://github.com/mem9-ai/mem9/tree/main/opencode-plugin#readme",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "memory",
+    "agent-memory",
+    "mem9",
+    "tidb",
+    "vector-search",
+    "persistent-memory",
+    "ai-agent"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "1.14.19"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "typescript": "^5.8.0"
+  },
+  "scripts": {
+    "test": "node ./scripts/test.mjs",
+    "pack:check": "pnpm pack --dry-run",
+    "publish:release": "node ./scripts/publish.mjs",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./server/index.js";

package/src/server/backend.ts

@@ -0,0 +1,39 @@
+import type {
+  CreateMemoryInput,
+  Memory,
+  SearchInput,
+  SearchResult,
+  StoreResult,
+  UpdateMemoryInput,
+} from "../shared/types.js";
+
+export interface IngestMessage {
+  role: string;
+  content: string;
+}
+
+export interface IngestInput {
+  messages: IngestMessage[];
+  session_id: string;
+  agent_id: string;
+  mode?: "smart";
+}
+
+export interface IngestResult {
+  status: string;
+  memories_changed?: number;
+}
+
+/**
+ * MemoryBackend — abstraction for server mode.
+ * All tools and hooks call through this interface.
+ */
+export interface MemoryBackend {
+  store(input: CreateMemoryInput): Promise<StoreResult>;
+  search(input: SearchInput): Promise<SearchResult>;
+  get(id: string): Promise<Memory | null>;
+  update(id: string, input: UpdateMemoryInput): Promise<Memory | null>;
+  remove(id: string): Promise<boolean>;
+  listRecent(limit: number): Promise<Memory[]>;
+  ingest(input: IngestInput): Promise<IngestResult>;
+}

package/src/server/config.ts

@@ -0,0 +1,251 @@
+import { readFile } from "node:fs/promises";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { parseCredentialsFile } from "../shared/credentials-store.js";
+import { DEFAULT_SCOPE_CONFIG } from "../shared/defaults.js";
+import {
+  resolveOpenCodeBasePaths,
+  resolveMem9Home,
+  resolveMem9Paths,
+  type Mem9ResolvedPaths,
+} from "../shared/platform-paths.js";
+import {
+  DEFAULT_API_URL,
+  type Mem9ConfigFile,
+  type Mem9CredentialsFile,
+} from "../shared/types.js";
+
+const EMPTY_CREDENTIALS: Mem9CredentialsFile = {
+  schemaVersion: 1,
+  profiles: {},
+};
+
+export interface EffectiveConfig extends Mem9ConfigFile {
+  paths?: Mem9ResolvedPaths;
+}
+
+export interface RuntimeIdentity {
+  apiKey: string;
+  baseUrl: string;
+  source: "env" | "legacy_env" | "profile";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeOptionalString(value: string | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeOptionalBoolean(value: string | undefined): boolean | undefined {
+  const normalized = normalizeOptionalString(value)?.toLowerCase();
+  if (!normalized) {
+    return undefined;
+  }
+
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+
+  return undefined;
+}
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error;
+}
+
+function normalizeConfigFile(value: unknown): Mem9ConfigFile {
+  if (!isRecord(value) || value.schemaVersion !== 1) {
+    throw new Error("invalid mem9 config file");
+  }
+
+  if ("profileId" in value && value.profileId !== undefined && typeof value.profileId !== "string") {
+    throw new Error("invalid mem9 config file");
+  }
+  if ("debug" in value && value.debug !== undefined && typeof value.debug !== "boolean") {
+    throw new Error("invalid mem9 config file");
+  }
+  if (
+    "defaultTimeoutMs" in value &&
+    value.defaultTimeoutMs !== undefined &&
+    typeof value.defaultTimeoutMs !== "number"
+  ) {
+    throw new Error("invalid mem9 config file");
+  }
+  if (
+    "searchTimeoutMs" in value &&
+    value.searchTimeoutMs !== undefined &&
+    typeof value.searchTimeoutMs !== "number"
+  ) {
+    throw new Error("invalid mem9 config file");
+  }
+
+  return {
+    schemaVersion: 1,
+    profileId: typeof value.profileId === "string" ? value.profileId : undefined,
+    debug: typeof value.debug === "boolean" ? value.debug : undefined,
+    defaultTimeoutMs:
+      typeof value.defaultTimeoutMs === "number" ? value.defaultTimeoutMs : undefined,
+    searchTimeoutMs:
+      typeof value.searchTimeoutMs === "number" ? value.searchTimeoutMs : undefined,
+  };
+}
+
+async function readConfigFile(filePath: string): Promise<Mem9ConfigFile | undefined> {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return normalizeConfigFile(JSON.parse(raw) as unknown);
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "ENOENT") {
+      return undefined;
+    }
+    console.warn("[mem9] Skipping unreadable mem9 config file.");
+    return undefined;
+  }
+}
+
+async function readCredentialsFile(filePath: string): Promise<Mem9CredentialsFile> {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return parseCredentialsFile(raw);
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "ENOENT") {
+      return EMPTY_CREDENTIALS;
+    }
+    console.warn("[mem9] Skipping unreadable mem9 credentials file.");
+    return EMPTY_CREDENTIALS;
+  }
+}
+
+function resolvePluginPaths(input: PluginInput): Mem9ResolvedPaths {
+  const basePaths = resolveOpenCodeBasePaths(process.env);
+  return resolveMem9Paths({
+    configDir: basePaths.configDir,
+    dataDir: basePaths.dataDir,
+    projectDir: input.worktree || input.directory,
+    mem9Home: resolveMem9Home(process.env),
+  });
+}
+
+export function mergeConfigLayers(
+  globalConfig?: Mem9ConfigFile,
+  projectConfig?: Mem9ConfigFile,
+): Mem9ConfigFile {
+  const merged: Mem9ConfigFile = {
+    schemaVersion: DEFAULT_SCOPE_CONFIG.schemaVersion,
+    debug: DEFAULT_SCOPE_CONFIG.debug,
+    defaultTimeoutMs: DEFAULT_SCOPE_CONFIG.defaultTimeoutMs,
+    searchTimeoutMs: DEFAULT_SCOPE_CONFIG.searchTimeoutMs,
+  };
+
+  for (const layer of [globalConfig, projectConfig]) {
+    if (!layer) {
+      continue;
+    }
+
+    if (layer.profileId !== undefined) {
+      merged.profileId = layer.profileId;
+    }
+    if (layer.debug !== undefined) {
+      merged.debug = layer.debug;
+    }
+    if (layer.defaultTimeoutMs !== undefined) {
+      merged.defaultTimeoutMs = layer.defaultTimeoutMs;
+    }
+    if (layer.searchTimeoutMs !== undefined) {
+      merged.searchTimeoutMs = layer.searchTimeoutMs;
+    }
+  }
+
+  return merged;
+}
+
+export function resolveRuntimeIdentity(
+  env: Record<string, string | undefined>,
+  credentials: Mem9CredentialsFile,
+  config: Mem9ConfigFile,
+): RuntimeIdentity | null {
+  const envApiKey = normalizeOptionalString(env.MEM9_API_KEY);
+  const envBaseUrl = normalizeOptionalString(env.MEM9_API_URL) ?? DEFAULT_API_URL;
+  const legacyTenantID = normalizeOptionalString(env.MEM9_TENANT_ID);
+  const profileID = normalizeOptionalString(config.profileId);
+
+  if (envApiKey) {
+    return {
+      apiKey: envApiKey,
+      baseUrl: envBaseUrl,
+      source: "env",
+    };
+  }
+
+  if (legacyTenantID) {
+    return {
+      apiKey: legacyTenantID,
+      baseUrl: envBaseUrl,
+      source: "legacy_env",
+    };
+  }
+
+  if (!profileID) {
+    return null;
+  }
+
+  const profile = credentials.profiles[profileID];
+  if (!profile) {
+    return null;
+  }
+
+  const profileApiKey = normalizeOptionalString(profile.apiKey);
+  if (!profileApiKey) {
+    return null;
+  }
+
+  return {
+    apiKey: profileApiKey,
+    baseUrl: normalizeOptionalString(profile.baseUrl) ?? DEFAULT_API_URL,
+    source: "profile",
+  };
+}
+
+export async function resolveEffectiveConfig(input: PluginInput): Promise<EffectiveConfig> {
+  const paths = resolvePluginPaths(input);
+
+  const [globalConfig, projectConfig] = await Promise.all([
+    readConfigFile(paths.globalConfigFile),
+    readConfigFile(paths.projectConfigFile),
+  ]);
+
+  const merged = mergeConfigLayers(globalConfig, projectConfig);
+  const envDebug = normalizeOptionalBoolean(process.env.MEM9_DEBUG);
+
+  return {
+    ...merged,
+    debug: envDebug ?? merged.debug,
+    paths,
+  };
+}
+
+export async function resolvePluginIdentity(
+  config: EffectiveConfig,
+): Promise<RuntimeIdentity | null> {
+  const envIdentity = resolveRuntimeIdentity(process.env, EMPTY_CREDENTIALS, config);
+  if (envIdentity && envIdentity.source !== "profile") {
+    return envIdentity;
+  }
+
+  if (!config.paths) {
+    return null;
+  }
+
+  const credentials = await readCredentialsFile(config.paths.credentialsFile);
+  return resolveRuntimeIdentity(process.env, credentials, config);
+}