@momomemory/opencode-momo 0.1.1

package/README.md

@@ -0,0 +1,202 @@
+# opencode-momo
+
+OpenCode plugin for persistent memory using [Momo](https://github.com/momomemory/momo).
+
+Your agent remembers what you tell it -- across sessions, across projects.
+
+## Installation
+
+### For Humans
+
+1. Install the plugin:
+   ```bash
+   bunx @momomemory/opencode-momo install
+   ```
+2. Configure your Momo connection:
+   ```bash
+   opencode-momo configure --base-url http://localhost:3000 --api-key YOUR_KEY
+   ```
+   Alternatively, set the following environment variables:
+   - `MOMO_BASE_URL` (default: `http://localhost:3000`)
+   - `MOMO_API_KEY`
+
+**Or let your agent do it** -- paste this into OpenCode:
+```
+Install opencode-momo by following https://raw.githubusercontent.com/momomemory/opencode-momo/main/README.md
+```
+
+### For LLM Agents
+
+<details>
+<summary>Instructions for LLM Agents (click to expand)</summary>
+
+If you're an LLM agent helping set up opencode-momo, follow these steps:
+
+#### Step 1: Run the installer
+
+```bash
+bunx @momomemory/opencode-momo install --yes
+```
+
+This will:
+- Register the plugin in `~/.config/opencode/opencode.jsonc`
+- Create the `/momo-init` and `/momo-configure` commands
+
+#### Step 2: Verify the config
+
+```bash
+cat ~/.config/opencode/opencode.jsonc
+```
+
+Should contain:
+```jsonc
+{
+  "plugin": [
+    "@momomemory/opencode-momo@latest"
+    // ... other plugins
+  ]
+}
+```
+
+If not, add it manually.
+
+#### Step 3: Configure connection
+
+Ask the user for their Momo server URL (default: `http://localhost:3000`) and optional API key.
+
+Then configure via CLI:
+
+```bash
+opencode-momo configure --base-url http://localhost:3000 --api-key YOUR_KEY
+```
+
+Or set environment variables:
+
+```bash
+export MOMO_BASE_URL=http://localhost:3000
+export MOMO_API_KEY=your-key
+```
+
+Or create `~/.config/opencode/momo.jsonc`:
+
+```jsonc
+{
+  "baseUrl": "http://localhost:3000",
+  "apiKey": "your-key"
+}
+```
+
+#### Step 4: Verify setup
+
+Tell the user to restart OpenCode. They should see `momo` in the tools list. If not, check:
+1. Is `MOMO_API_KEY` set (or is the server running without auth)?
+2. Is the plugin in `opencode.jsonc`?
+
+#### Step 5: Initialize codebase memory (optional)
+
+Run `/momo-init` to have the agent explore and memorize the codebase.
+
+</details>
+
+## Features
+
+### Context Injection
+Momo automatically injects relevant context into the first message of every chat session. This includes:
+- **User Profile**: A computed narrative of your preferences and known facts.
+- **User Memories**: Recent personal context across all projects.
+- **Project Memories**: Specific knowledge related to the current codebase.
+
+### Tool Modes
+The `momo` tool supports 6 operational modes:
+- **help**: Show usage information.
+- **add**: Store a new memory with a specified scope and type.
+- **search**: Perform a hybrid search across user and project memories.
+- **profile**: View the computed user profile.
+- **list**: List recent memories for a given scope.
+- **forget**: Remove a specific memory by its ID.
+
+### Codebase Indexing
+The `/momo-init` command provides a structured workflow for agents to explore a new codebase and store its architecture, conventions, and key facts into project memory.
+
+### Event Compaction
+Momo listens for `session.compacted` events. When a session is compacted, the plugin automatically ingests the conversation history into Momo to ensure long-term retention of session insights. A 30-second cooldown is enforced per session to prevent redundant ingestion.
+
+### Privacy
+Momo supports the `<private>` tag. Any content wrapped in `<private>` tags is automatically stripped before being stored in memory. If a message consists entirely of private content, it will not be stored.
+
+## Tool Usage
+
+| Mode | Required Args | Optional Args | Description |
+|------|--------------|---------------|-------------|
+| help | — | — | Show help text |
+| add | content | scope, memoryType | Store a memory |
+| search | query | scope, limit | Search memories |
+| profile | — | scope | View computed user profile |
+| list | — | scope, limit | List recent memories |
+| forget | memoryId | — | Forget a memory by ID |
+
+**Scopes**: `user` (cross-project), `project` (current project, default)  
+**Memory Types**: `fact`, `preference`, `episode`
+
+## Memory Scoping
+
+Memories are isolated using container tags derived from your environment:
+
+| Scope | Description | Tag Derivation |
+|-------|-------------|-----------------------|
+| **user** | Personal facts and preferences shared across all projects | `opencode-user-{hash(username)}` |
+| **project** | Codebase-specific knowledge | `ocp-{slug(projectName)}-{hash(directory)}` |
+
+## Configuration
+
+Configuration is stored in `~/.config/opencode/momo.jsonc`:
+
+```jsonc
+{
+  // Momo server URL
+  "baseUrl": "http://localhost:3000",
+  // API key for authentication
+  "apiKey": "your-key-here"
+}
+```
+
+### Environment Variables
+
+The following variables can be used to override configuration:
+- `MOMO_BASE_URL`: Overrides `baseUrl` in config.
+- `MOMO_API_KEY`: Overrides `apiKey` in config.
+- `MOMO_CONTAINER_TAG_USER`: Override the default user container tag.
+- `MOMO_CONTAINER_TAG_PROJECT`: Override the default project container tag.
+
+## Development
+
+1. Install dependencies:
+   ```bash
+   bun install
+   ```
+2. Build the plugin:
+   ```bash
+   bun run build
+   ```
+3. Run typecheck:
+   ```bash
+   bun run typecheck
+   ```
+4. Run tests:
+   ```bash
+   bun test
+   ```
+
+### Local Installation
+
+To test the plugin locally in OpenCode, add a file URL to your `opencode.jsonc`:
+
+```jsonc
+{
+  "plugin": ["file:///path/to/opencode-momo"]
+}
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Register the plugin in OpenCode's opencode.jsonc config.
+ * Returns true if a change was made, false if already registered.
+ */
+export declare function registerPluginInConfig(configDir: string): boolean;
+/**
+ * Write the markdown command files into the command directory.
+ * Returns an object indicating which files were written.
+ */
+export declare function writeCommandFiles(configDir: string): {
+    initWritten: boolean;
+    configureWritten: boolean;
+};
+/**
+ * Write or update the momo.jsonc config file.
+ */
+export declare function writeMomoConfig(configDir: string, options: {
+    baseUrl?: string;
+    apiKey?: string;
+}): void;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAyIA;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA8CjE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAWA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,IAAI,CA2CN"}

package/dist/cli.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/cli.ts
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync
+} from "node:fs";
+import { join as join2 } from "node:path";
+import { createInterface } from "node:readline";
+
+// src/config.ts
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// src/services/jsonc.ts
+function stripJsoncComments(content) {
+  let result = "";
+  let i = 0;
+  let inString = false;
+  let inSingleLineComment = false;
+  let inMultiLineComment = false;
+  while (i < content.length) {
+    const char = content[i];
+    const nextChar = content[i + 1];
+    if (!inSingleLineComment && !inMultiLineComment) {
+      if (char === '"') {
+        let backslashCount = 0;
+        let j = i - 1;
+        while (j >= 0 && content[j] === "\\") {
+          backslashCount++;
+          j--;
+        }
+        if (backslashCount % 2 === 0) {
+          inString = !inString;
+        }
+        result += char;
+        i++;
+        continue;
+      }
+    }
+    if (inString) {
+      result += char;
+      i++;
+      continue;
+    }
+    if (!inSingleLineComment && !inMultiLineComment) {
+      if (char === "/" && nextChar === "/") {
+        inSingleLineComment = true;
+        i += 2;
+        continue;
+      }
+      if (char === "/" && nextChar === "*") {
+        inMultiLineComment = true;
+        i += 2;
+        continue;
+      }
+    }
+    if (inSingleLineComment) {
+      if (char === `
+`) {
+        inSingleLineComment = false;
+        result += char;
+      }
+      i++;
+      continue;
+    }
+    if (inMultiLineComment) {
+      if (char === "*" && nextChar === "/") {
+        inMultiLineComment = false;
+        i += 2;
+        continue;
+      }
+      if (char === `
+`) {
+        result += char;
+      }
+      i++;
+      continue;
+    }
+    result += char;
+    i++;
+  }
+  return result.replace(/,\s*([}\]])/g, "$1");
+}
+
+// src/config.ts
+function getConfigDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg) {
+    return join(xdg, "opencode");
+  }
+  return join(homedir(), ".config", "opencode");
+}
+
+// src/cli.ts
+var PLUGIN_NAME = "@momomemory/opencode-momo@latest";
+var MOMO_INIT_MD = `---
+description: Initialize Momo with comprehensive codebase knowledge
+---
+
+# Initializing Momo Memory
+
+You are initializing persistent memory for this codebase. Your goal is to explore the project thoroughly and store key information so that future sessions have full context without re-exploration.
+
+## Steps
+
+1. **Explore the project structure** — Understand the directory layout, key files, and architecture.
+2. **Identify conventions** — Note coding style, naming patterns, testing approach, and tooling.
+3. **Record architectural decisions** — Store how the codebase is organized and why.
+4. **Save key facts** — Store important facts about the project using Momo.
+
+## How to Store Memories
+
+Use the \`momo\` tool to save what you learn:
+
+\`\`\`
+momo({ mode: "add", content: "This project uses a monorepo with Cargo workspaces", scope: "project", memoryType: "fact" })
+momo({ mode: "add", content: "User prefers concise code comments", scope: "user", memoryType: "preference" })
+\`\`\`
+
+### Scopes
+- **\`user\`** — Personal preferences and facts that apply across all projects
+- **\`project\`** — Information specific to this codebase
+
+### Memory Types
+- **\`fact\`** — Objective information (architecture, tech stack, file locations)
+- **\`preference\`** — Subjective preferences (coding style, tool choices)
+- **\`episode\`** — Events or interactions worth remembering
+
+## What to Capture
+
+- Programming languages and frameworks used
+- Build system and development commands
+- Project structure and key directories
+- Testing patterns and test locations
+- Deployment and CI/CD configuration
+- Important conventions and patterns
+- Key dependencies and their purposes
+- Any README or documentation highlights
+
+Start by listing the top-level files and directories, then progressively explore the most important areas of the codebase. Store each significant finding as a memory.
+`;
+var MOMO_CONFIGURE_MD = `---
+description: Configure Momo memory connection
+---
+
+# Configure Momo
+
+Run this command to configure the Momo connection:
+
+\`\`\`bash
+bunx @momomemory/opencode-momo configure
+\`\`\`
+
+Or set environment variables:
+- \`MOMO_BASE_URL\` - Momo server URL (default: http://localhost:3000)
+- \`MOMO_API_KEY\` - API key for authentication
+
+After configuration, restart OpenCode to activate.
+`;
+function parseArgs(argv) {
+  const flags = {};
+  let command;
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      flags["help"] = true;
+    } else if (arg === "--yes" || arg === "-y") {
+      flags["yes"] = true;
+    } else if (arg === "--no-prompt") {
+      flags["no-prompt"] = true;
+    } else if (arg === "--base-url" && i + 1 < argv.length) {
+      i++;
+      flags["base-url"] = argv[i];
+    } else if (arg === "--api-key" && i + 1 < argv.length) {
+      i++;
+      flags["api-key"] = argv[i];
+    } else if (!arg.startsWith("-") && !command) {
+      command = arg;
+    }
+  }
+  return { command, flags };
+}
+async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+async function promptInput(question, defaultValue) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  return new Promise((resolve) => {
+    rl.question(`${question}${suffix}: `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+function registerPluginInConfig(configDir) {
+  const configPath = join2(configDir, "opencode.jsonc");
+  if (existsSync(configPath)) {
+    const content = readFileSync(configPath, "utf-8");
+    if (content.includes(PLUGIN_NAME)) {
+      return false;
+    }
+    if (content.includes('"plugin"')) {
+      const newContent = content.replace(/("plugin"\s*:\s*\[)([^\]]*?)(\])/, (_match, start, middle, end) => {
+        const trimmed = middle.trim();
+        if (trimmed === "") {
+          return `${start}
+    "${PLUGIN_NAME}"
+  ${end}`;
+        }
+        return `${start}${middle.trimEnd()},
+    "${PLUGIN_NAME}"
+  ${end}`;
+      });
+      writeFileSync(configPath, newContent, "utf-8");
+      return true;
+    }
+    const beforeBrace = content.trimEnd().slice(0, -1).trimEnd();
+    if (beforeBrace.endsWith(",") || beforeBrace.endsWith("{")) {
+      const insertContent = content.replace(/\}\s*$/, `  "plugin": [
+    "${PLUGIN_NAME}"
+  ]
+}`);
+      writeFileSync(configPath, insertContent, "utf-8");
+    } else {
+      const withComma = content.replace(/(\S)\s*\}\s*$/, `$1,
+  "plugin": [
+    "${PLUGIN_NAME}"
+  ]
+}`);
+      writeFileSync(configPath, withComma, "utf-8");
+    }
+    return true;
+  }
+  mkdirSync(configDir, { recursive: true });
+  const newConfig = `{
+  "plugin": [
+    "${PLUGIN_NAME}"
+  ]
+}
+`;
+  writeFileSync(configPath, newConfig, "utf-8");
+  return true;
+}
+function writeCommandFiles(configDir) {
+  const commandDir = join2(configDir, "command");
+  mkdirSync(commandDir, { recursive: true });
+  const initPath = join2(commandDir, "momo-init.md");
+  const configurePath = join2(commandDir, "momo-configure.md");
+  writeFileSync(initPath, MOMO_INIT_MD, "utf-8");
+  writeFileSync(configurePath, MOMO_CONFIGURE_MD, "utf-8");
+  return { initWritten: true, configureWritten: true };
+}
+function writeMomoConfig(configDir, options) {
+  const configPath = join2(configDir, "momo.jsonc");
+  mkdirSync(configDir, { recursive: true });
+  let existing = {};
+  if (existsSync(configPath)) {
+    try {
+      const raw = readFileSync(configPath, "utf-8");
+      const stripped = stripJsoncComments(raw);
+      existing = JSON.parse(stripped);
+    } catch {
+      existing = {};
+    }
+  }
+  const priorBaseUrl = typeof existing.baseUrl === "string" ? existing.baseUrl : undefined;
+  const priorApiKey = typeof existing.apiKey === "string" ? existing.apiKey : undefined;
+  const priorContainerTagUser = typeof existing.containerTagUser === "string" ? existing.containerTagUser : undefined;
+  const priorContainerTagProject = typeof existing.containerTagProject === "string" ? existing.containerTagProject : undefined;
+  const config = {
+    baseUrl: options.baseUrl ?? priorBaseUrl ?? "http://localhost:3000",
+    apiKey: options.apiKey ?? priorApiKey ?? "",
+    containerTagUser: priorContainerTagUser ?? "",
+    containerTagProject: priorContainerTagProject ?? ""
+  };
+  const lines = ["{"];
+  lines.push("  // Momo server URL");
+  lines.push(`  "baseUrl": ${JSON.stringify(config.baseUrl)},`);
+  lines.push("  // API key for authentication (leave empty if your server has auth disabled)");
+  lines.push(`  "apiKey": ${JSON.stringify(config.apiKey)},`);
+  lines.push("  // Optional override for user memory container tag (default: auto-derived from username)");
+  lines.push(`  "containerTagUser": ${JSON.stringify(config.containerTagUser)},`);
+  lines.push("  // Optional override for project memory container tag (default: auto-derived from project directory)");
+  lines.push(`  "containerTagProject": ${JSON.stringify(config.containerTagProject)}`);
+  lines.push("}");
+  lines.push("");
+  writeFileSync(configPath, lines.join(`
+`), "utf-8");
+}
+async function runInstall(flags) {
+  const autoYes = flags["yes"] === true || flags["no-prompt"] === true;
+  const configDir = getConfigDir();
+  console.log(`
+\uD83D\uDD27 Step 1: Register plugin in OpenCode config
+`);
+  if (!autoYes) {
+    const ok = await confirm("Register @momomemory/opencode-momo in OpenCode config?");
+    if (!ok) {
+      console.log("  Skipped.");
+      return;
+    }
+  }
+  const changed = registerPluginInConfig(configDir);
+  if (changed) {
+    console.log(`  ✓ Plugin registered in ${join2(configDir, "opencode.jsonc")}`);
+  } else {
+    console.log("  ✓ Plugin already registered in config");
+  }
+  console.log(`
+\uD83D\uDCDD Step 2: Create command files
+`);
+  if (!autoYes) {
+    const ok = await confirm("Create momo-init.md and momo-configure.md command files?");
+    if (!ok) {
+      console.log("  Skipped.");
+      return;
+    }
+  }
+  writeCommandFiles(configDir);
+  console.log(`  ✓ Created ${join2(configDir, "command", "momo-init.md")}`);
+  console.log(`  ✓ Created ${join2(configDir, "command", "momo-configure.md")}`);
+  console.log(`
+✅ Installation complete!
+
+Next steps:
+  1. Set your Momo API key:
+     $ opencode-momo configure --base-url http://localhost:3000 --api-key YOUR_KEY
+
+     Or set environment variables:
+     $ export MOMO_API_KEY=your-key
+     $ export MOMO_BASE_URL=http://localhost:3000
+
+  2. Restart OpenCode to activate the plugin.
+
+  3. Use /momo-init to initialize memory for your codebase.
+`);
+}
+async function runConfigure(flags) {
+  const configDir = getConfigDir();
+  let baseUrl = typeof flags["base-url"] === "string" ? flags["base-url"] : undefined;
+  let apiKey = typeof flags["api-key"] === "string" ? flags["api-key"] : undefined;
+  if (baseUrl === undefined && apiKey === undefined) {
+    const isTTY = process.stdin.isTTY;
+    if (isTTY) {
+      baseUrl = await promptInput("Momo server URL", "http://localhost:3000");
+      apiKey = await promptInput("API key");
+    } else {
+      console.error(`No --base-url or --api-key provided, and stdin is not a TTY.
+` + "Usage: opencode-momo configure --base-url URL --api-key KEY");
+      process.exit(1);
+    }
+  }
+  writeMomoConfig(configDir, { baseUrl, apiKey });
+  console.log(`
+✓ Configuration written to ${join2(configDir, "momo.jsonc")}`);
+  if (apiKey) {
+    console.log("  ✓ API key set");
+  }
+  if (baseUrl) {
+    console.log(`  ✓ Base URL: ${baseUrl}`);
+  }
+  console.log(`
+Restart OpenCode to apply changes.`);
+}
+function printHelp() {
+  console.log(`opencode-momo v0.1.1
+
+OpenCode plugin that gives coding agents persistent memory using Momo.
+
+USAGE:
+  opencode-momo <command> [options]
+
+COMMANDS:
+  install       Install and configure the plugin for OpenCode
+  configure     Update Momo connection settings
+  help          Show this help message
+
+INSTALL OPTIONS:
+  --yes, -y     Skip confirmation prompts
+  --no-prompt   Same as --yes
+
+CONFIGURE OPTIONS:
+  --base-url    Momo server URL (default: http://localhost:3000)
+  --api-key     API key for authentication
+
+GENERAL OPTIONS:
+  -h, --help    Show this help message
+`);
+}
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  if (!command || command === "help" || flags["help"] === true) {
+    printHelp();
+    process.exit(0);
+  }
+  if (command === "install") {
+    await runInstall(flags);
+    return;
+  }
+  if (command === "configure") {
+    await runConfigure(flags);
+    return;
+  }
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "opencode-momo --help" for usage.');
+  process.exit(1);
+}
+if (__require.main == __require.module) {
+  main().catch((err) => {
+    console.error("Error:", err instanceof Error ? err.message : err);
+    process.exit(1);
+  });
+}
+export {
+  writeMomoConfig,
+  writeCommandFiles,
+  registerPluginInConfig
+};

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface MomoConfig {
+    apiKey?: string;
+    baseUrl: string;
+    containerTagUser?: string;
+    containerTagProject?: string;
+}
+export declare function getConfigDir(): string;
+export declare function loadConfig(): MomoConfig;
+export declare function isConfigured(): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAWD,wBAAgB,YAAY,IAAI,MAAM,CAMrC;AAaD,wBAAgB,UAAU,IAAI,UAAU,CAYvC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAGtC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const MomoPlugin: Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,qBAAqB,CAAC;AAoC/D,eAAO,MAAM,UAAU,EAAE,MAmSxB,CAAC"}