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

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"]
}

Configure your embedding API key (see Configuration below)
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/

优先级

用户上下文文件（最高优先级）
项目上下文文件
存储的记忆（通过 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

User context file (~/.config/opencode/freememory-context.md)
Project context file (.opencode/freememory-context.md)
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.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Freememory

Why Freememory?

⚠️ Security Notice

Installation

Manual Install

Configuration

Configuration File Locations

Creating Your Config

Environment Variables (Alternative)

Context Files (手动记忆)

用户级上下文文件

项目级上下文文件

优先级

📝 Context Files (Manual Memory)

User-level Context File

Project-level Context File

Priority Order

Supported Embedding Providers

SiliconFlow (Recommended for Chinese users)

OpenAI

Custom Provider

Features

Context Injection

Keyword Detection

Memory Scoping

Tool Usage

Data Storage

Backup

Clear All Memories

Compatibility with oh-my-opencode

Development

License

Credits

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages