@ninkch/opencode-mem

OpenCode plugin for persistent local memory - fully offline, no API keys required.

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

Features

• 100% Local - All data stored locally, no cloud dependencies
• No API Keys - No registration, no subscription, completely free
• Offline Capable - Works without internet after initial model download
• Semantic Search - Find relevant memories using natural language
• Cross-Session Memory - Agent remembers across conversations
• Multi-language - Supports 100+ languages including Chinese

Installation

Option 1: Install from npm

npm install -g @ninkch/opencode-mem
opencode-mem install
opencode-mem init
opencode -c

Option 2: Local Clone

git clone https://github.com/NINKCH/opencode-mem.git
cd opencode-mem
npm install
npm run build
node dist/cli.js install
node dist/cli.js init
opencode -c

Usage

Automatic Memory Injection

When you start a new conversation, the plugin automatically injects relevant context:

User: Help me add a new API endpoint

[Agent receives]:
[LOCAL-MEMORY]

Project Knowledge:
- [100%] Uses Bun runtime
- [100%] API routes in /src/api

Relevant Memories:
- [85%] REST API follows JSON:API spec

Saving Memories

Use keywords to trigger automatic saving:

User: Remember that this project uses bun instead of npm
Agent: [Automatically saves to project memory]

Supported keywords: remember, save this, don't forget, learn this, 记住, 记下

Tool Commands

The agent can use the local-memory tool:

| Mode | Description | |------|-------------| | add | Store a new memory | | search | Search memories | | list | List all memories | | forget | Delete a memory | | profile | View user profile |

Scopes:

• user - Cross-project preferences (e.g., "I prefer concise responses", "Use 2-space indentation")
• project - Project-specific knowledge (default, e.g., "Architecture uses microservices", "API key in .env")

CLI Commands

opencode-mem install              # Install plugin
opencode-mem init                 # Initialize storage
opencode-mem status               # Show status
opencode-mem memories list        # List current project memories
opencode-mem memories list --all  # List ALL project memories (cross-project)
opencode-mem memories list --project <name>  # List specific project memories
opencode-mem memories list --scope user  # List user preferences
opencode-mem memories show <id>   # Show memory details with path
opencode-mem memories search "x"  # Search memories
opencode-mem memories add "text"  # Add project memory
opencode-mem memories add "text" --scope user  # Add user preference
opencode-mem memories clear --force # Delete all memories
opencode-mem export backup.json   # Export memories
opencode-mem import backup.json   # Import memories

Scopes

The memory system uses two scopes to organize memories:

User Scope (--scope user)

• Purpose: Cross-project preferences and knowledge
• Examples: "I prefer concise responses", "Use 2-space indentation", "Always add comments"
• Storage: No project association (projectName=null)
• Query: Available in ALL projects

Project Scope (default, --scope project)

• Purpose: Project-specific knowledge and configurations
• Examples: "API routes in /src/api", "Uses PostgreSQL database", "Error in module X"
• Storage: Associated with project name and path
• Query: Available only in the current project (by default)

Cross-Project Query

Use --all flag to list memories from ALL projects:

opencode-mem memories list --all

This ignores the project tag and shows memories from all projects.

Configuration

Create ~/.config/opencode/memory.json:

{
  "similarityThreshold": 0.6,
  "maxMemories": 5,
  "keywordPatterns": ["记住", "save this"]
}

Requirements

• Node.js 18+ or Bun
• ~500MB disk space (for embedding model)

Comparison

| Feature | opencode-supermemory | @ninkch/opencode-mem | |---------|---------------------|----------------------| | API Key | Required | Not required | | Data Storage | Cloud | Local | | Cost | Paid | Free | | Offline | No | Yes |

Development

git clone https://github.com/NINKCH/opencode-mem.git
cd opencode-mem
npm install
npm run build
npm run typecheck

License

MIT