Content
# Fuga Memory
Claude Code (and other LLMs) long-term memory MCP server.
Saves conversation content to SQLite and retrieves relevant memories using hybrid search with FTS5 (full-text search) + vector search (ruri-v3-310m).
## Features
- **No external dependencies**: Stores all data in a single SQLite file
- **Hybrid search**: Integrates FTS5 keyword search + vector search with RRF
- **Time decay**: Gradually decreases score of older memories with a half-life of 30 days
- **Lightweight inference**: Runs ruri-v3-310m on CPU with ONNX backend
- **MCP compatible**: Shareable with multiple LLMs like Claude Code, Gemini, and Copilot
- **Auto-save**: Automatically saves session data at the end of a session with Claude Code's Stop hook
## Setup Guide
- [Setup with Claude Code (CLAUDE.md)](CLAUDE.md)
- [Setup with Gemini CLI (docs/gemini-guide.md)](docs/gemini-guide.md)
## Quick Start
### 1. Installation
```bash
git clone https://github.com/densuke/fuga-memory
cd fuga-memory
uv sync
```
> **First launch**: Automatically downloads the ruri-v3-310m model and converts it to ONNX format (approximately 600MB, several tens of seconds). The converted model is cached in `~/.local/share/fuga-memory/onnx_cache/` for faster launches on subsequent runs.
### 2. Configure (optional)
Skip this step if you're using the default settings. Copy the template to customize:
```bash
# macOS
mkdir -p ~/Library/Application\ Support/fuga-memory
cp config.toml.example ~/Library/Application\ Support/fuga-memory/config.toml
# Linux
mkdir -p ~/.config/fuga-memory
cp config.toml.example ~/.config/fuga-memory/config.toml
```
### 3. Register with Claude Code
Open `~/.claude/settings.json` and add the following:
If you also want to use auto-save with the Stop hook, include the `hooks` section as-is. If not, remove the `hooks` section.
```json
{
"mcpServers": {
"fuga-memory": {
"command": "uv",
"args": ["run", "--project", "/path/to/fuga-memory", "fuga-memory", "serve"]
}
},
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "uv run --project /path/to/fuga-memory fuga-memory save --stdin --session-id \"${CLAUDE_SESSION_ID:-unknown}\" --source claude_code",
"timeout": 60
}
]
}
]
}
}
```
### 4. Verify
Restart Claude Code to enable the MCP tool. Try chatting with Claude:
```
You can use the search_memory tool with fuga-memory.
Try searching for "Python's asyncio".
```
## MCP Server Mechanism
`fuga-memory serve` runs with **stdio transport**:
```
Claude Code ←─ stdin/stdout ─→ fuga-memory serve (child process)
```
**Key points:**
- Claude Code reads the `mcpServers` configuration and **automatically starts and stops the process as needed**
- No need to manually start a resident server
- No HTTP port is used
### Auto-save mechanism with Stop hook
```
Session end
↓
Claude Code executes Stop hook
↓
fuga-memory save --stdin --session-id <id> (short-lived, one-time process)
↓
Save completed in SQLite
```
The Stop hook operates independently of the MCP server. The MCP server does not need to be running when the hook is executed.
## Usage with Claude Code
Once the MCP tool is enabled, you can use the following three tools:
### save_memory — Save memory
```
save_memory(content="Studied Python's asyncio today", session_id="my-session")
```
| Argument | Type | Description |
|------|----|------|
| `content` | str | Text to save (required) |
| `session_id` | str | Session identifier (required) |
| `source` | str | Source identifier (default: `"manual"`) |
### search_memory — Search memory
```
search_memory(query="Python's asynchronous processing", top_k=5)
```
| Argument | Type | Description |
|------|----|------|
| `query` | str | Search query (required) |
| `top_k` | int | Maximum number of results to return (default: 5) |
Returns: `[{"id", "score", "content", "session_id", "source", "created_at"}, ...]` (in descending order of score)
### list_sessions — List sessions
```
list_sessions(limit=20)
```
Returns: `[{"session_id", "memory_count", "last_updated"}, ...]`
## CLI Reference
Can be operated directly from the command line, not through MCP.
### serve — Start MCP server
```bash
uv run fuga-memory serve
uv run fuga-memory --debug serve # Debug mode without suppressing library warnings
```
Usually, there's no need to manually start it. Claude Code manages it automatically.
Used when connecting with other MCP clients (e.g., Gemini CLI) or for verification.
### search — Search memory
```bash
uv run fuga-memory search "About Rust's lifetime"
uv run fuga-memory search "Python" --top-k 10
```
### save — Save memory
Three types of input methods are available:
```bash
# Pass directly as an argument
uv run fuga-memory save "Learned today" --session-id my-session
# Read from a file
uv run fuga-memory save --file notes.txt --session-id my-session
# Read from standard input (pipe)
echo "Content to pass through pipe" | uv run fuga-memory save --stdin --session-id my-session
cat transcript.txt | uv run fuga-memory save --stdin --session-id my-session
```
## Configuration
### Configuration file (recommended)
Explores the following order and uses the first one found:
| Priority | OS | Path |
|--------|-----|------|
| 1 | macOS | `~/Library/Application Support/fuga-memory/config.toml` |
| 2 | Linux / common | `$XDG_CONFIG_HOME/fuga-memory/config.toml` (if not set: `~/.config/fuga-memory/config.toml`) |
| 3 | common | `~/.fuga-memory.toml` |
**Create from template:**
```bash
cp config.toml.example ~/.config/fuga-memory/config.toml # Linux
cp config.toml.example ~/Library/Application\ Support/fuga-memory/config.toml # macOS
```
**Example configuration:**
```toml
[fuga-memory]
db_path = "~/.local/share/fuga-memory/memories.db"
decay_halflife_days = 14 # Change memory half-life to 2 weeks
default_top_k = 10
```
### Environment variables
Takes precedence over configuration files. For environments like Docker/CI where file placement is difficult.
| Variable | Default | Description |
|------|-----------|------|
| `FUGA_MEMORY_DB_PATH` | `~/.local/share/fuga-memory/memories.db` | DB file path |
| `FUGA_MEMORY_MODEL_NAME` | `cl-nagoya/ruri-v3-310m` | Embedding model |
| `FUGA_MEMORY_THREAD_WORKERS` | CPU count ÷ 2 | Inference thread count |
| `FUGA_MEMORY_RRF_K` | `60` | RRF's k parameter |
| `FUGA_MEMORY_DECAY_HALFLIFE_DAYS` | `30` | Time decay half-life (days) |
| `FUGA_MEMORY_DEFAULT_TOP_K` | `5` | Default search results |
| `FUGA_MEMORY_DAEMON_PORT` | `18520` | Daemon listening port |
| `FUGA_MEMORY_DAEMON_IDLE_TIMEOUT` | `600` | Daemon idle auto-exit (seconds) |
| `FUGA_MEMORY_ONNX_CACHE_DIR` | `~/.local/share/fuga-memory/onnx_cache` | ONNX cache directory |
| `FUGA_MEMORY_DEBUG` | `false` | Debug mode (without suppressing warnings) |
See `.env.example` for details.
### Priority
```
Default value < Configuration file < Environment variable
```
## Data locations
| Item | Default path |
|------|--------------|
| DB file | `~/.local/share/fuga-memory/memories.db` |
| ONNX cache | `~/.local/share/fuga-memory/onnx_cache/` |
| Model cache | `~/.cache/huggingface/` |
The DB file is a single SQLite file. Backup with `cp memories.db memories.db.bak`.
## Technical stack
- Python 3.13, uv, fastmcp
- SQLite + FTS5 (trigram tokenizer) + sqlite-vec
- sentence-transformers + cl-nagoya/ruri-v3-310m (ONNX backend)
- ThreadPoolExecutor + asyncio
## Inspiration
This project was inspired by noprogllama's Zenn article:
**[Giving Claude Code long-term memory changed the quality of my interactions](https://zenn.dev/noprogllama/articles/7c24b2c2410213)**
The article introduced design ideas such as storing data in a single SQLite file, hybridizing FTS5 and vector search, integrating with RRF, and time decay scoring. fuga-memory started with these ideas and added its own implementation with Python + fastmcp, enhanced security, and flexible configuration.
Thanks to noprogllama for sharing excellent design ideas.
## License
MIT
