Freememory

OpenCode plugin for persistent local memory with custom embedding providers.

Your agent remembers what you tell it - across sessions, across projects. All data stored locally.

Why Freememory?

This is a local alternative to supermemory that:

• Stores all data locally - No data uploaded to external servers
• Uses your own embedding API - Supports SiliconFlow, OpenAI, or any OpenAI-compatible API
• Zero external dependencies for storage - SQLite database on your machine

⚠️ Security Notice

You MUST configure your own API key. This plugin does NOT include any built-in API keys.

• Your embedding API key is stored locally in your configuration file
• The key is never transmitted anywhere except to your configured embedding provider
• DO NOT commit your configuration file to version control

Installation

Manual Install

1. Add to your OpenCode config:

User-level config (applies to all projects):

# Edit: ~/.config/opencode/opencode.json

Project-level config (only for this project):

# Edit: .opencode/opencode.json

Add the plugin:

{
  "plugin": ["file:///root/freememory"]
}

Or if installed via npm:

{
  "plugin": ["opencode-freememory"]
}

2. Configure your embedding API key (see Configuration below)

3. Restart OpenCode

Configuration

Configuration File Locations

Following the same convention as oh-my-opencode:

| Level | Path | Description | |-------|------|-------------| | User-level | ~/.config/opencode/freememory.json | Applies to all projects | | Project-level | .opencode/freememory.json | Only for this project |

Project-level config overrides user-level config.

Creating Your Config

Create ~/.config/opencode/freememory.json (user-level) or .opencode/freememory.json (project-level):

{
  // REQUIRED: Configure your own embedding API
  "embedding": {
    "provider": "siliconflow",  // "siliconflow", "openai", or "custom"
    "baseURL": "https://api.siliconflow.cn/v1",
    "apiKey": "YOUR_API_KEY_HERE",  // <-- Replace with your own key
    "model": "netease-youdao/bce-embedding-base_v1",
    "dimensions": 768
  },
  
  // Memory retrieval settings (optional)
  "similarityThreshold": 0.6,
  "maxMemories": 5,
  "maxProjectMemories": 10,
  "maxProfileItems": 5,
  
  // Context injection (optional)
  "injectProfile": true,
  
  // Container tags (optional, auto-generated if not set)
  "containerTagPrefix": "freememory",
  
  // Keyword detection patterns (optional)
  "keywordPatterns": [
    "remember",
    "save this",
    "don't forget",
    "write down",
    "log this",
    "记住",
    "记得",
    "保存"
  ],
  
  // Compaction (disabled by default to avoid conflicts with oh-my-opencode)
  "compaction": {
    "enabled": false,
    "threshold": 0.8
  }
}

Environment Variables (Alternative)

You can also set the API key via environment variables:

export FREEMEMORY_API_KEY="YOUR_API_KEY_HERE"
export FREEMEMORY_BASE_URL="https://api.siliconflow.cn/v1"  # optional
export FREEMEMORY_MODEL="netease-youdao/bce-embedding-base_v1"  # optional

Environment variables override config file values.

| Variable | Description | |----------|-------------| | FREEMEMORY_API_KEY | Embedding API key (overrides config file) | | FREEMEMORY_BASE_URL | Embedding API base URL (overrides config file) | | FREEMEMORY_MODEL | Embedding model name (overrides config file) | | FREEMEMORY_DEBUG | Set to "true" to enable debug logging |

Context Files (手动记忆)

你可以直接编辑文本文件来为 OpenCode 提供上下文，无需使用工具命令。

用户级上下文文件

路径: ~/.config/opencode/freememory-context.md

适用于所有项目。写入你的全局偏好。

示例:

# 用户偏好

- 总是使用 TypeScript
- 偏好函数式编程风格
- 使用有意义的变量名
- 只在必要时添加注释
- 提交前运行测试

项目级上下文文件

路径: .opencode/freememory-context.md（项目根目录）

仅适用于当前项目。写入项目特定的知识。

示例:

# 项目知识

## 技术栈
- 前端: React + TypeScript + Vite
- 后端: Node.js + Express
- 数据库: PostgreSQL

## 命令
- pnpm dev - 启动开发服务器
- pnpm build - 生产构建
- pnpm test - 运行测试

## 约定
- 使用 pnpm，不用 npm
- 组件放在 src/components/
- API 路由在 src/api/

优先级

1. 用户上下文文件（最高优先级）
2. 项目上下文文件
3. 存储的记忆（通过 freememory 工具添加）

两个上下文文件都是可选的。如果不存在，插件仍然可以正常工作。

| Variable | Description | |----------|-------------| | FREEMEMORY_API_KEY | Embedding API key (overrides config file) | | FREEMEMORY_BASE_URL | Embedding API base URL (overrides config file) | | FREEMEMORY_MODEL | Embedding model name (overrides config file) | | FREEMEMORY_DEBUG | Set to "true" to enable debug logging |

📝 Context Files (Manual Memory)

You can write natural language instructions in text files. These files are automatically loaded at the start of each session:

User-level Context File

Path: ~/.config/opencode/freememory-context.md

Applies to all projects. Write your global preferences here.

Example:

# User Preferences

- Always use TypeScript for new files
- Prefer functional programming style
- Use meaningful variable names
- Add comments only when necessary
- Run tests before committing

Project-level Context File

Path: .opencode/freememory-context.md (in project root)

Applies only to this project. Write project-specific knowledge here.

Example:

# Project Knowledge

## Tech Stack
- Frontend: React + TypeScript + Vite
- Backend: Node.js + Express
- Database: PostgreSQL

## Commands
- `pnpm dev` - Start development server
- `pnpm build` - Production build
- `pnpm test` - Run tests

## Conventions
- Use pnpm, not npm
- Components go in src/components/
- API routes in src/api/

Priority Order

1. User context file (~/.config/opencode/freememory-context.md)
2. Project context file (.opencode/freememory-context.md)
3. Stored memories (via freememory tool)

Both context files are optional. If they don't exist, the plugin will still work with stored memories.

| Variable | Description | |----------|-------------| | FREEMEMORY_API_KEY | Embedding API key (overrides config file) | | FREEMEMORY_BASE_URL | Embedding API base URL (overrides config file) | | FREEMEMORY_MODEL | Embedding model name (overrides config file) | | FREEMEMORY_DEBUG | Set to "true" to enable debug logging |

Supported Embedding Providers

SiliconFlow (Recommended for Chinese users)

Get your API key from siliconflow.cn:

{
  "embedding": {
    "provider": "siliconflow",
    "baseURL": "https://api.siliconflow.cn/v1",
    "apiKey": "YOUR_SILICONFLOW_API_KEY",
    "model": "netease-youdao/bce-embedding-base_v1"
  }
}

OpenAI

Get your API key from platform.openai.com:

{
  "embedding": {
    "provider": "openai",
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "YOUR_OPENAI_API_KEY",
    "model": "text-embedding-3-small"
  }
}

Custom Provider

Any OpenAI-compatible embedding API:

{
  "embedding": {
    "provider": "custom",
    "baseURL": "https://your-api.com/v1",
    "apiKey": "YOUR_API_KEY",
    "model": "your-model-name"
  }
}

Features

Context Injection

On first message, the agent receives (invisible to user):

• User profile (cross-project preferences)
• Project memories (all project knowledge)
• Relevant user memories (semantic search)

Example of what the agent sees:

[FREEMEMORY]

User Profile:
- Prefers concise responses
- Expert in TypeScript

Project Knowledge:
- Uses Bun, not Node.js
- Build: bun run build

Relevant Memories:
- [82%] Build fails if .env.local missing

Keyword Detection

Say "remember", "save this", "don't forget", "记住", etc. and the agent auto-saves to memory.

You: "Remember that this project uses bun"
Agent: [saves to project memory]

Memory Scoping

| Scope | Description | Persists | |-------|-------------|----------| | user | Cross-project preferences | All projects | | project | Project-specific knowledge | This project |

Tool Usage

The freememory tool is available to the agent:

| Mode | Args | Description | |------|------|-------------| | add | content, type?, scope? | Store memory | | search | query, scope? | Search memories | | profile | - | View user profile | | list | scope?, limit? | List memories | | forget | memoryId | Delete memory | | stats | - | View statistics | | help | - | Show usage guide |

Memory Types:

• project-config - Build commands, environment setup
• architecture - System design decisions
• error-solution - Known issues and fixes
• preference - User preferences
• learned-pattern - Code patterns
• conversation - Important context

Data Storage

All data is stored locally in:

~/.config/opencode/freememory/
├── freememory.db    # SQLite database
└── logs/            # Optional logs

Backup

To backup your memories:

cp ~/.config/opencode/freememory/freememory.db ~/freememory-backup.db

Clear All Memories

rm ~/.config/opencode/freememory/freememory.db

Compatibility with oh-my-opencode

Freememory is compatible with oh-my-opencode.

The compaction feature is disabled by default to avoid conflicts with oh-my-opencode's preemptive-compaction hook.

If you want to use freememory's compaction feature, disable oh-my-opencode's hook:

User-level (~/.config/opencode/oh-my-opencode.json):

{
  "disabled_hooks": ["anthropic-context-window-limit-recovery", "preemptive-compaction"]
}

Project-level (.opencode/oh-my-opencode.json):

{
  "disabled_hooks": ["anthropic-context-window-limit-recovery", "preemptive-compaction"]
}

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Local install (for testing)
# In your opencode.json:
{
  "plugin": ["file:///root/freememory"]
}

License

MIT

Credits

Inspired by supermemory, but with local storage and custom embedding providers.