@mem9/opencode 0.1.1 → 0.1.2

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.2",
   "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

@@ -27,7 +27,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 +50,17 @@ export interface SetupActionOption {
   description: string;
 }
 
+export interface SetupProfileOption {
+  title: string;
+  value: string;
+  description: string;
+  disabled: boolean;
+}
+
+interface SetupProfileOptionState {
+  currentProfileId?: string;
+}
+
 function getProjectDir(api: TuiPluginApi): string {
   const worktree = api.state.path.worktree.trim();
   if (worktree.length > 0) {
@@ -155,12 +166,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 +179,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 +314,7 @@ function showActionDialog(
           return;
         }
 
-        showScopeDialog(api, paths, state, "full-config");
+        showScopeDialog(api, paths, state, "settings-only");
       },
     }),
   );
@@ -459,7 +494,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 +509,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);
       },
     }),
   );
@@ -550,7 +581,7 @@ function showDefaultTimeoutDialog(
         showSearchTimeoutDialog(api, paths, state, draft);
       },
       onCancel: () => {
-        showScopeProfileDialog(api, paths, state, "full-config", draft);
+        showScopeDebugDialog(api, paths, state, draft);
       },
     }),
   );