@mem9/opencode 0.1.1 → 0.1.3

package/README.md

@@ -2,82 +2,40 @@
 
 Persistent memory for [OpenCode](https://opencode.ai).
 
-The package ships two plugin entrypoints:
+This package has two 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
+### 1. Install mem9 once at user scope
 
-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"]
-}
+```bash
+opencode plugin --global @mem9/opencode
 ```
 
-Avoid duplicate plugin loading, such as:
+That adds `@mem9/opencode` to these files:
 
-- user scope plugin plus project scope plugin
-- npm plugin plus local file plugin
+macOS/Linux:
 
-### 2. Install the TUI plugin for `/mem9-setup`
+- `~/.config/opencode/opencode.json`
+- `~/.config/opencode/tui.json`
 
-File: `~/.config/opencode/tui.json`
+Windows:
 
-```json
-{
-  "plugin": ["@mem9/opencode"]
-}
-```
+- `%APPDATA%\\opencode\\opencode.json`
+- `%APPDATA%\\opencode\\tui.json`
 
-That enables the `/mem9-setup` command inside OpenCode.
+mem9 works best with one global plugin install plus project `mem9.json` overrides.
+OpenCode merges plugin lists across scopes, so one install keeps recall, ingest, and tools predictable.
 
-### 3. Restart OpenCode and run `/mem9-setup`
+### 2. Restart OpenCode and run `/mem9-setup`
 
-`/mem9-setup` is the single entrypoint for both:
+`/mem9-setup` is the main entrypoint for:
 
 - shared mem9 credentials
-- OpenCode user/project mem9 settings
+- OpenCode mem9 settings
 
 When no usable profile exists, it shows two actions:
 
@@ -89,32 +47,45 @@ 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`
+- `Adjust scope settings`
 
-Profile creation ends after the profile is saved. Scope configuration is a separate action.
+The last two actions do different things:
 
-## File Layout
+- `Use an existing mem9 profile in a scope` changes which profile a user or project scope uses
+- `Adjust scope settings` changes `debug`, `defaultTimeoutMs`, and `searchTimeoutMs` for a user or project scope
 
-OpenCode config directory:
+### 3. Add project overrides only when you need them
 
-- macOS/Linux: usually `~/.config/opencode`
-- Windows: usually `%APPDATA%\\opencode`
+Keep the plugin install global.
+Use `<project>/.opencode/mem9.json` when one repository needs a different profile, debug flag, or timeout.
 
-OpenCode state directory:
+Example:
 
-- macOS/Linux: usually `~/.local/share/opencode`
-- Windows: usually `%LOCALAPPDATA%\\opencode`
+```json
+{
+  "schemaVersion": 1,
+  "profileId": "default",
+  "debug": false,
+  "defaultTimeoutMs": 8000,
+  "searchTimeoutMs": 15000
+}
+```
 
-mem9 uses these files:
+## Where mem9 stores data
 
-- 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`
+- Shared credentials:
+  macOS/Linux: `$HOME/.mem9/.credentials.json`
+  Windows: `%USERPROFILE%\\.mem9\\.credentials.json`
+- Global mem9 config:
+  macOS/Linux: `~/.config/opencode/mem9.json`
+  Windows: `%APPDATA%\\opencode\\mem9.json`
+- Project mem9 override:
+  all platforms: `<project>/.opencode/mem9.json`
+- Debug logs:
+  macOS/Linux: `~/.local/share/opencode/plugins/mem9/log/YYYY-MM-DD.jsonl`
+  Windows: `%LOCALAPPDATA%\\opencode\\plugins\\mem9\\log\\YYYY-MM-DD.jsonl`
 
-`MEM9_HOME` defaults to `$HOME/.mem9`.
+`MEM9_HOME` defaults to `$HOME/.mem9` on macOS/Linux and `%USERPROFILE%\\.mem9` on Windows.
 
 ## Credentials File
 
@@ -173,33 +144,33 @@ These environment variables still override disk config at runtime:
 - `MEM9_DEBUG`
 - `MEM9_HOME`
 
-Legacy compatibility remains:
+Legacy compatibility:
 
 - `MEM9_TENANT_ID`
 
 `MEM9_TENANT_ID` is treated as the API key source for older setups.
 
-## Local Development Install
+## Upgrading
 
-You can also point OpenCode at a local checkout.
+OpenCode caches npm plugins by package specifier.
+When config points at `@mem9/opencode`, OpenCode resolves it as `@mem9/opencode@latest`.
 
-Server plugin example:
+Upgrade flow:
 
-```json
-{
-  "plugin": ["./.opencode/plugins/mem9/src/index.ts"]
-}
-```
+1. Quit OpenCode.
+2. Delete the cached folder that matches the installed specifier.
+   macOS/Linux default: `~/.cache/opencode/packages/@mem9/opencode@latest`
+   Windows default: `%LOCALAPPDATA%\\opencode\\packages\\@mem9\\opencode@latest`
+   If you pinned an exact version such as `@mem9/opencode@0.1.1`, delete that exact folder name instead.
+3. Run:
 
-TUI plugin example:
-
-```json
-{
-  "plugin": ["./.opencode/plugins/mem9/src/tui/index.ts"]
-}
+```bash
+opencode plugin --force --global @mem9/opencode
 ```
 
-Keep the same one-scope rule for the server plugin even when using local paths.
+4. Restart OpenCode.
+
+For prerelease testing, install an explicit npm specifier such as `@mem9/opencode@rc` or an exact version.
 
 ## What the Plugin Does
 
@@ -211,7 +182,7 @@ The server plugin does three things:
 
 ### Hook Flow
 
-OpenCode integration currently uses four runtime hooks:
+OpenCode integration uses four runtime hooks:
 
 | Hook | What mem9 does |
 | --- | --- |
@@ -253,16 +224,8 @@ The plugin registers these tools:
 ## 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 `/mem9-setup` is missing, confirm `@mem9/opencode` is listed in your global `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

@@ -1,15 +1,12 @@
 {
   "name": "@mem9/opencode",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
+    "./server": "./src/index.ts",
     "./tui": "./src/tui/index.ts"
   },
   "license": "Apache-2.0",

package/src/shared/setup-files.ts

@@ -17,6 +17,7 @@ export interface SetupProfileSummary {
   label: string;
   baseUrl: string;
   hasApiKey: boolean;
+  apiKeyPreview: string;
 }
 
 export interface ScopeConfigState {
@@ -112,6 +113,23 @@ function hasApiKey(profile: unknown): boolean {
   return Boolean(normalizeOptionalString(profile.apiKey));
 }
 
+function summarizeApiKeyPreview(apiKey: string): string {
+  const normalized = apiKey.trim();
+  if (normalized.length === 0) {
+    return "";
+  }
+
+  if (normalized.length <= 4) {
+    return `${normalized.slice(0, 1)}...`;
+  }
+
+  if (normalized.length <= 8) {
+    return `${normalized.slice(0, 2)}...${normalized.slice(-2)}`;
+  }
+
+  return `${normalized.slice(0, 4)}...${normalized.slice(-4)}`;
+}
+
 function normalizeProfileRecord(
   profileId: string,
   profile: Mem9Profile | undefined,
@@ -188,6 +206,7 @@ function buildProfiles(
         label: normalized.label,
         baseUrl: normalized.baseUrl,
         hasApiKey: normalized.apiKey.trim().length > 0,
+        apiKeyPreview: summarizeApiKeyPreview(normalized.apiKey),
       };
     })
     .sort(sortProfileSummaries);

package/src/tui/index.ts

@@ -3,6 +3,7 @@ import type {
   TuiCommand,
   TuiPlugin,
   TuiPluginApi,
+  TuiToast,
 } from "@opencode-ai/plugin/tui";
 import {
   resolveMem9Home,
@@ -27,7 +28,7 @@ type SetupAction =
   | "use-profile-in-scope"
   | "configure-scope";
 
-type ScopeFlowMode = "profile-only" | "full-config";
+type ScopeFlowMode = "profile-only" | "settings-only";
 
 interface ProfileDraft {
   profileId: string;
@@ -50,6 +51,33 @@ export interface SetupActionOption {
   description: string;
 }
 
+export interface SetupProfileOption {
+  title: string;
+  value: string;
+  description: string;
+  disabled: boolean;
+}
+
+interface SetupProfileOptionState {
+  currentProfileId?: string;
+}
+
+let hasShownVisibleApiKeyWarning = false;
+const DEFAULT_TOAST_DURATION_MS = 5000;
+
+function scheduleDialogTransition(next: () => void): void {
+  // Delay prompt-to-prompt transitions so the next dialog does not reuse
+  // the same Enter keypress that confirmed the current prompt.
+  setTimeout(next, 0);
+}
+
+function showToast(api: TuiPluginApi, toast: TuiToast): void {
+  api.ui.toast({
+    duration: toast.duration ?? DEFAULT_TOAST_DURATION_MS,
+    ...toast,
+  });
+}
+
 function getProjectDir(api: TuiPluginApi): string {
   const worktree = api.state.path.worktree.trim();
   if (worktree.length > 0) {
@@ -102,7 +130,7 @@ function showError(
   retryCommand = false,
 ): void {
   const suffix = retryCommand ? " Run /mem9-setup again when you are ready to retry." : "";
-  api.ui.toast({
+  showToast(api, {
     variant: "error",
     title: "mem9 setup failed",
     message: `${error instanceof Error ? error.message : String(error)}${suffix}`,
@@ -110,7 +138,7 @@ function showError(
 }
 
 function showProfileSavedSuccess(api: TuiPluginApi, profileId: string): void {
-  api.ui.toast({
+  showToast(api, {
     variant: "success",
     title: "mem9 configured",
     message: `Saved profile ${profileId} and set it as the default user profile. Restart OpenCode to reload mem9.`,
@@ -123,7 +151,7 @@ function showScopeSavedSuccess(
   profileId: string,
 ): void {
   const scopeLabel = scope === "user" ? "user settings" : "project settings";
-  api.ui.toast({
+  showToast(api, {
     variant: "success",
     title: "mem9 configured",
     message: `Saved ${scopeLabel} with profile ${profileId}. Restart OpenCode to reload mem9.`,
@@ -155,12 +183,12 @@ export function buildSetupActionOptions(
       {
         title: "Use an existing mem9 profile in a scope",
         value: "use-profile-in-scope",
-        description: "Choose a saved profile and apply it to user or project settings.",
+        description: "Choose which saved profile user or project settings should use.",
       },
       {
-        title: "Configure user/project settings",
+        title: "Adjust scope settings",
         value: "configure-scope",
-        description: "Change scope profile, debug logging, and request timeouts.",
+        description: "Change debug logging, request timeouts, and other mem9 settings for a user or project scope.",
       },
     );
   }
@@ -168,6 +196,30 @@ export function buildSetupActionOptions(
   return options;
 }
 
+function formatProfileTitle(profile: SetupProfileSummary): string {
+  return profile.label === profile.profileId
+    ? profile.label
+    : `${profile.label} (${profile.profileId})`;
+}
+
+export function buildScopeProfileOptions(
+  state: Pick<SetupState, "profiles">,
+  optionState: SetupProfileOptionState = {},
+): SetupProfileOption[] {
+  return state.profiles.map((profile) => ({
+    title: formatProfileTitle(profile),
+    value: profile.profileId,
+    description: [
+      profile.apiKeyPreview || "API key missing",
+      profile.baseUrl,
+      profile.profileId === optionState.currentProfileId ? "Current in this scope" : undefined,
+    ]
+      .filter((value): value is string => Boolean(value))
+      .join(" | "),
+    disabled: !profile.hasApiKey,
+  }));
+}
+
 function parsePositiveInteger(value: string, field: string): number | null {
   const trimmed = value.trim();
   if (trimmed.length === 0) {
@@ -279,7 +331,7 @@ function showActionDialog(
           return;
         }
 
-        showScopeDialog(api, paths, state, "full-config");
+        showScopeDialog(api, paths, state, "settings-only");
       },
     }),
   );
@@ -300,7 +352,7 @@ function showProfileIdDialog(
       onConfirm: (value) => {
         const next = value.trim();
         if (next.length === 0) {
-          api.ui.toast({
+          showToast(api, {
             variant: "warning",
             message: "Profile ID is required.",
           });
@@ -308,7 +360,7 @@ function showProfileIdDialog(
         }
 
         if (isReusableProfileID(state, next)) {
-          api.ui.toast({
+          showToast(api, {
             variant: "warning",
             message: "That profile already has credentials. Pick a new profile ID or use the existing profile in scope settings.",
           });
@@ -319,7 +371,9 @@ function showProfileIdDialog(
         if (draft.label.trim().length === 0) {
           draft.label = next === "default" ? "Personal" : next;
         }
-        showProfileLabelDialog(api, paths, state, action, draft);
+        scheduleDialogTransition(() => {
+          showProfileLabelDialog(api, paths, state, action, draft);
+        });
       },
       onCancel: () => {
         showActionDialog(api, paths, state);
@@ -343,7 +397,7 @@ function showProfileLabelDialog(
       onConfirm: (value) => {
         const next = value.trim();
         if (next.length === 0) {
-          api.ui.toast({
+          showToast(api, {
             variant: "warning",
             message: "Profile label is required.",
           });
@@ -351,10 +405,14 @@ function showProfileLabelDialog(
         }
 
         draft.label = next;
-        showProfileBaseUrlDialog(api, paths, state, action, draft);
+        scheduleDialogTransition(() => {
+          showProfileBaseUrlDialog(api, paths, state, action, draft);
+        });
       },
       onCancel: () => {
-        showProfileIdDialog(api, paths, state, action, draft);
+        scheduleDialogTransition(() => {
+          showProfileIdDialog(api, paths, state, action, draft);
+        });
       },
     }),
   );
@@ -375,7 +433,7 @@ function showProfileBaseUrlDialog(
       onConfirm: (value) => {
         const next = value.trim();
         if (next.length === 0) {
-          api.ui.toast({
+          showToast(api, {
             variant: "warning",
             message: "mem9 API URL is required.",
           });
@@ -388,10 +446,14 @@ function showProfileBaseUrlDialog(
           return;
         }
 
-        showProfileApiKeyDialog(api, paths, state, draft);
+        scheduleDialogTransition(() => {
+          showProfileApiKeyDialog(api, paths, state, draft);
+        });
       },
       onCancel: () => {
-        showProfileLabelDialog(api, paths, state, action, draft);
+        scheduleDialogTransition(() => {
+          showProfileLabelDialog(api, paths, state, action, draft);
+        });
       },
     }),
   );
@@ -403,11 +465,14 @@ function showProfileApiKeyDialog(
   state: SetupState,
   draft: ProfileDraft,
 ): void {
-  api.ui.toast({
-    variant: "warning",
-    message: "The current OpenCode prompt is plain text. Your API key stays visible while typing.",
-    duration: 4000,
-  });
+  if (!hasShownVisibleApiKeyWarning) {
+    hasShownVisibleApiKeyWarning = true;
+    showToast(api, {
+      variant: "warning",
+      message: "API key input is visible while typing.",
+      duration: 4000,
+    });
+  }
 
   api.ui.dialog.replace(() =>
     api.ui.DialogPrompt({
@@ -416,7 +481,7 @@ function showProfileApiKeyDialog(
       onConfirm: (value) => {
         const next = value.trim();
         if (next.length === 0) {
-          api.ui.toast({
+          showToast(api, {
             variant: "warning",
             message: "mem9 API key is required.",
           });
@@ -427,7 +492,9 @@ function showProfileApiKeyDialog(
         void submitManualProfile(api, paths, draft);
       },
       onCancel: () => {
-        showProfileBaseUrlDialog(api, paths, state, "manual-api-key", draft);
+        scheduleDialogTransition(() => {
+          showProfileBaseUrlDialog(api, paths, state, "manual-api-key", draft);
+        });
       },
     }),
   );
@@ -459,7 +526,12 @@ function showScopeDialog(
       ],
       onSelect: (option) => {
         const draft = createScopeDraft(state, option.value);
-        showScopeProfileDialog(api, paths, state, mode, draft);
+        if (mode === "profile-only") {
+          showScopeProfileDialog(api, paths, state, draft);
+          return;
+        }
+
+        showScopeDebugDialog(api, paths, state, draft);
       },
     }),
   );
@@ -469,27 +541,18 @@ function showScopeProfileDialog(
   api: TuiPluginApi,
   paths: Mem9ResolvedPaths,
   state: SetupState,
-  mode: ScopeFlowMode,
   draft: ScopeDraft,
 ): void {
   api.ui.dialog.replace(() =>
     api.ui.DialogSelect<string>({
       title: "Which mem9 profile should this scope use?",
       current: draft.profileId,
-      options: state.profiles.map((profile) => ({
-        title: `${profile.label} (${profile.profileId})`,
-        value: profile.profileId,
-        description: `${profile.baseUrl} • ${profile.hasApiKey ? "API key configured" : "API key missing"}`,
-        disabled: !profile.hasApiKey,
-      })),
+      options: buildScopeProfileOptions(state, {
+        currentProfileId: draft.profileId,
+      }),
       onSelect: (option) => {
         draft.profileId = option.value;
-        if (mode === "profile-only") {
-          void submitScopeConfigDraft(api, paths, draft);
-          return;
-        }
-
-        showScopeDebugDialog(api, paths, state, draft);
+        void submitScopeConfigDraft(api, paths, draft);
       },
     }),
   );
@@ -539,7 +602,7 @@ function showDefaultTimeoutDialog(
       onConfirm: (value) => {
         const parsed = parsePositiveInteger(value, "defaultTimeoutMs");
         if (parsed === null) {
-          api.ui.toast({
+          showToast(api, {
             variant: "warning",
             message: "Default timeout must be a positive integer.",
           });
@@ -547,10 +610,12 @@ function showDefaultTimeoutDialog(
         }
 
         draft.defaultTimeoutMs = parsed;
-        showSearchTimeoutDialog(api, paths, state, draft);
+        scheduleDialogTransition(() => {
+          showSearchTimeoutDialog(api, paths, state, draft);
+        });
       },
       onCancel: () => {
-        showScopeProfileDialog(api, paths, state, "full-config", draft);
+        showScopeDebugDialog(api, paths, state, draft);
       },
     }),
   );
@@ -570,7 +635,7 @@ function showSearchTimeoutDialog(
       onConfirm: (value) => {
         const parsed = parsePositiveInteger(value, "searchTimeoutMs");
         if (parsed === null) {
-          api.ui.toast({
+          showToast(api, {
             variant: "warning",
             message: "Search timeout must be a positive integer.",
           });
@@ -581,7 +646,9 @@ function showSearchTimeoutDialog(
         void submitScopeConfigDraft(api, paths, draft);
       },
       onCancel: () => {
-        showDefaultTimeoutDialog(api, paths, state, draft);
+        scheduleDialogTransition(() => {
+          showDefaultTimeoutDialog(api, paths, state, draft);
+        });
       },
     }),
   );