OpenCode Integration for Forgetful

Custom commands and skills for using Forgetful with OpenCode.

Prerequisites

Ensure you have:

• OpenCode installed
• uvx available (comes with uv)

MCP Server Configuration

Add Forgetful to your OpenCode configuration file (opencode.json or opencode.jsonc):

Standard Setup (Recommended)

Zero-config setup using SQLite storage:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "forgetful": {
      "type": "local",
      "command": ["uvx", "forgetful-ai"],
      "enabled": true
    }
  }
}

Your memories will persist in ~/.forgetful/forgetful.db.

Custom Setup (Advanced)

For PostgreSQL, custom embeddings, or remote servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "forgetful": {
      "type": "local",
      "command": ["uvx", "forgetful-ai"],
      "enabled": true,
      "environment": {
        "DATABASE": "Postgres",
        "POSTGRES_HOST": "localhost",
        "PGPORT": "5432",
        "POSTGRES_DB": "forgetful",
        "POSTGRES_USER": "user",
        "POSTGRES_PASSWORD": "pass",
        "EMBEDDING_PROVIDER": "Google",
        "EMBEDDING_MODEL": "models/text-embedding-001"
      }
    }
  }
}

Remote HTTP Server

For connecting to a Forgetful instance running elsewhere:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "forgetful": {
      "type": "remote",
      "url": "http://localhost:8020/mcp",
      "enabled": true,
    }
  }
}

See configuration.md for all available environment variables.

Installation

Commands

Copy command files to your OpenCode commands directory:

# Global installation
cp docs/opencode/commands/*.md ~/.config/opencode/command/

# Or project-specific
cp docs/opencode/commands/*.md .opencode/command/

Skills

Skills are maintained once, in the canonical skills/ directory at the repository root. Copy them to your OpenCode skills directory:

# Global installation
cp -r skills/forgetful-* ~/.config/opencode/skill/

# Or project-specific
cp -r skills/forgetful-* .opencode/skill/

Available Commands

Command	Description
/forgetful-setup	Configure the Forgetful MCP server
/memory-search	Search memories semantically
/memory-save	Save current context as an atomic memory with curation workflow
/memory-list	List recent memories from Forgetful
/memory-explore	Deep exploration of the Forgetful knowledge graph
/encode-repo	Bootstrap a repository into Forgetful's knowledge base

Available Skills

Skills are automatically discovered by OpenCode and loaded on-demand via the skill tool.

The OpenCode-specific skills previously documented here have been superseded by the global skill set. See skills/README.md for the full catalog.

Usage Examples

Search Memories

Find relevant context from your knowledge base:

/memory-search authentication patterns

Save a Memory

After a conversation with important insights:

/memory-save

The command analyzes the conversation, checks for related memories, and proposes an atomic memory with proper curation.

List Recent Memories

See what's been added recently:

/memory-list 10

Explore the Knowledge Graph

Deep traversal of related memories, entities, and documents:

/memory-explore payment processing

Encode a Repository

Bootstrap a new project into Forgetful:

/encode-repo my-project

Command Format

OpenCode commands are Markdown files with YAML frontmatter:

---
description: Brief description shown in TUI
---
Template text with $ARGUMENTS placeholder

Supported placeholders:

• $ARGUMENTS - All passed arguments combined
• $1, $2, $3 - Individual positional arguments
• !`command` - Shell command output injection
• @path/to/file - File content injection

See the OpenCode commands documentation for more details.

Skill Format

OpenCode skills are SKILL.md files in named folders:

---
name: skill-name
description: What the skill does and when to use it
---
# Skill Content
Detailed guidance for the agent...

See the OpenCode skills documentation for more details.

Troubleshooting

MCP Server Not Found

Verify uvx is installed:

which uvx

If not found, install uv: https://docs.astral.sh/uv/getting-started/installation/

Connection Timeout

Increase the timeout in your configuration:

{
  "mcp": {
    "forgetful": {
      "type": "local",
      "command": ["uvx", "forgetful-ai"],
      "timeout": 60000
    }
  }
}

Check Server Status

For HTTP servers, verify the endpoint is accessible:

curl http://localhost:8020/health

View Logs

Check Forgetful logs at ~/.forgetful/forgetful.log (if logging is enabled).