opencode-momo

OpenCode plugin for persistent memory using Momo.

Your agent remembers what you tell it -- across sessions, across projects.

Installation

For Humans

1. Install the plugin:

   bunx @momomemory/opencode-momo install

2. Configure your Momo connection:

   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

If you're an LLM agent helping set up opencode-momo, follow these steps:

Step 1: Run the installer

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

cat ~/.config/opencode/opencode.jsonc

Should contain:

{
  "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:

opencode-momo configure --base-url http://localhost:3000 --api-key YOUR_KEY

Or set environment variables:

export MOMO_BASE_URL=http://localhost:3000
export MOMO_API_KEY=your-key

Or create ~/.config/opencode/momo.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.

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.

Ingestion Tools (RAG Pipeline)

For richer ingestion than plain read, the plugin also exposes dedicated tools that route through Momo's document pipeline:

• momo_ingest: Ingest text, URLs, or local files into documents + retrieval index, with optional memory extraction.
• momo_ocr: Ingest image files, run OCR, and optionally extract memories from recognized text.
• momo_transcribe: Ingest audio/video files, run transcription, and optionally extract memories.

These tools are especially useful with non-vision models: image/audio content is converted into searchable text in Momo.

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

Ingestion Tool Arguments (high-level)

| Tool | Required Args | Optional Args | |------|--------------|---------------| | momo_ingest | input | inputType, scope, extractMemories, metadataJson, contentType, wait, timeoutMs, pollIntervalMs | | momo_ocr | filePath | scope, extractMemories, contentType, wait, timeoutMs, pollIntervalMs | | momo_transcribe | filePath | scope, extractMemories, contentType, wait, timeoutMs, pollIntervalMs |

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:

{
  // Momo server URL
  "baseUrl": "http://localhost:3000",
  // API key for authentication
  "apiKey": "your-key-here",
  // Optional override for user memory container tag
  "containerTagUser": "",
  // Optional override for project memory container tag
  "containerTagProject": ""
}

Project-local config (optional)

You can also place config in your project root as .momo.jsonc (preferred) or momo.jsonc. This is useful when you want a stable containerTagProject for a specific repo.

Config precedence

Highest to lowest precedence:

1. Environment variables (MOMO_*)
2. Project-local config (.momo.jsonc / momo.jsonc)
3. Global config (~/.config/opencode/momo.jsonc)
4. Built-in defaults

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:

   bun install

2. Build the plugin:

   bun run build

3. Run typecheck:

   bun run typecheck

4. Run tests:

   bun test

Local Installation

To test the plugin locally in OpenCode, add a file URL to your opencode.jsonc:

{
  "plugin": ["file:///path/to/opencode-momo"]
}

License

MIT