Fuga Memory

fuga记忆

用于Claude Code（和其他LLM）的长期存储MCP服务器。

将对话内容保存到SQLite中，通过FTS5（全文检索）+矢量检索（ruri-v3-310m）的混合检索调用相关的存储。

特徴

• 无外部依赖关系：将所有数据存储在SQLite单一文件中
• 混合搜索：FTS5关键字检索+矢量检索用RRF合并
• 时间减衰：将旧记忆的分数在半衰期30天阶段性降低
• 軽量推论：在ONNX后端用CPU运行ruri-v3-310m
• MCP 対応：Claude Code/Gemini/Copilot等多个LLM共享
• 自动保存：使用Claude Code的Stop挂钩在会话结束时自动保存

安装指南

• Claude Code中的设置（CLAUDE.md）
• Gemini CLI中的设置（docs/gemini-guide.md）

______________________________________________________________________

快速启动

1.安装

git clone https://github.com/densuke/fuga-memory
cd fuga-memory
uv sync

初回起动时：自动下载ruri-v3-310m机型并转换成ONNX格式（约600MB·数十秒）。已转换的模型 ~/.local/share/fuga-memory/onnx_cache/ 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

2.配置配置配置文件（任意）

如果仍使用默认设置，则可以跳过。如果要自定义，请复制模板。

# 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.注册Claude Code

~/.claude/settings.json 打开并添加以下内容（/path/to/fuga-memory ），模板名称将采用不同的格式。

使用Stop挂钩自动保存时 hooks 请直接包含节。不使用的情况下 hooks 请删除节。

{
  "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.动作确认

重新启动Claude Code后，将启用MCP工具。请试着和Claude搭话。

あなたはfuga-memoryの search_memory ツールを使えます。
「Python の asyncio について」と検索してみてください。

______________________________________________________________________

MCP服务器的结构

fuga-memory serve 啊 stdio传输 中所述修改相应参数的值。

Claude Code ←─ stdin/stdout ─→ fuga-memory serve (子プロセス)

要点：

• Claude Code mcpServers 的设置根据需要自动启动和停止进程做
• 不需要手动启动驻留服务器
• 也不使用HTTP端口

如何在停止钩上自动保存

セッション終了
    ↓
Claude Code が Stop フックを実行
    ↓
fuga-memory save --stdin --session-id   （短命な1回限りのプロセス）
    ↓
SQLite に保存完了

Stop挂钩独立于MCP服务器运行。当挂钩运行时，MCP服务器不需要启动。

______________________________________________________________________

Claude Code中的使用方法

当MCP工具生效时，可以使用以下三种工具。

save_memory—保存记忆

save_memory(content="今日Pythonのasyncioを勉強した", session_id="my-session")

search_memory—查找记忆

search_memory(query="Pythonの非同期処理", top_k=5)

返回值： [{"id", "score", "content", "session_id", "source", "created_at"}, ...]（得分降順）

list_sessions—会话列表

list_sessions(limit=20)

返回值： [{"session_id", "memory_count", "last_updated"}, ...]

______________________________________________________________________

CLI参考

不是通过MCP，而是可以从命令行直接操作。

启动服务器-MCP服务器

uv run fuga-memory serve
uv run fuga-memory --debug serve   # ライブラリ警告を抑制しないデバッグモード

通常不需要手动启动。由Claude Code自动管理。 与其他MCP客户端（Gemini CLI等）连接或确认动作时使用。

搜索记忆

uv run fuga-memory search "Rustのlifetimeについて"
uv run fuga-memory search "Python" --top-k 10

保存记忆

有三种输入法。

# 引数として直接渡す
uv run fuga-memory save "今日学んだこと" --session-id my-session

# ファイルから読み込む
uv run fuga-memory save --file notes.txt --session-id my-session

# 標準入力から読み込む（パイプ）
echo "パイプで渡す内容" | uv run fuga-memory save --stdin --session-id my-session
cat transcript.txt | uv run fuga-memory save --stdin --session-id my-session

______________________________________________________________________

设定

配置文件（推荐）

按以下顺序搜索并使用第一个找到的内容：。

｜优先级｜OS｜路径｜ |--------|-----|------| |1|macOS| ~/Library/Application Support/fuga-memory/config.toml | | 2 | Linux / 共通 | $XDG_CONFIG_HOME/fuga-memory/config.toml（未设定时： ~/.config/fuga-memory/config.toml） | | 3 | 共通 | ~/.fuga-memory.toml |

从模板创建：

cp config.toml.example ~/.config/fuga-memory/config.toml  # Linux
cp config.toml.example ~/Library/Application\ Support/fuga-memory/config.toml  # macOS

设定例：

[fuga-memory]
db_path = "~/.local/share/fuga-memory/memories.db"
decay_halflife_days = 14   # 記憶の半減期を2週間に変更
default_top_k = 10

环境变数

优先于配置文件。适用于Docker/CI等难以配置文件的环境。

｜变量｜默认｜说明｜ |------|-----------|------| | FUGA_MEMORY_DB_PATH | ~/.local/share/fuga-memory/memories.db 数据库文件路径 | FUGA_MEMORY_MODEL_NAME | cl-nagoya/ruri-v3-310m ｜嵌入模型｜ | FUGA_MEMORY_THREAD_WORKERS ｜CPU数÷2｜推理线程数｜ | FUGA_MEMORY_RRF_K | 60 ｜RRF的k参数｜ | FUGA_MEMORY_DECAY_HALFLIFE_DAYS | 30 时间衰减的半衰期（天） | FUGA_MEMORY_DEFAULT_TOP_K | 5 ｜默认搜索件数｜ | FUGA_MEMORY_DAEMON_PORT | 18520 后台进程的等待端口 | FUGA_MEMORY_DAEMON_IDLE_TIMEOUT | 600 后台进程的空闲自动结束（秒） | FUGA_MEMORY_ONNX_CACHE_DIR | ~/.local/share/fuga-memory/onnx_cache ｜ONNX高速缓存目录｜ | FUGA_MEMORY_DEBUG | false ｜调试模式（不抑制警告）｜

了解更多信息 .env.example 来修改标记元素的显示属性。

优先顺位

デフォルト値  <  設定ファイル  <  環境変数

______________________________________________________________________

数据位置

｜项目｜默认路径｜ |------|--------------| 数据库文件 ~/.local/share/fuga-memory/memories.db | ｜ONNX高速缓存｜ ~/.local/share/fuga-memory/onnx_cache/ | 模型高速缓存 ~/.cache/huggingface/ |

数据库文件是SQLite单一文件。备份是 cp memories.db memories.db.bak 来修改标记元素的显示属性。

______________________________________________________________________

技术栈

• Python 3.13、uv、fastmcp
• SQLite+FTS5（trigram谈话器）+sqlite-vec
• sentence-transformers+cl-nagoya/ruri-v3-310m（ONNX后端）
• 线程池执行器+异步

灵感

这个项目是noprogllama先生的Zenn报道

如果让Claude Code有长期记忆的话，打墙的质量就变了

的规格化距离的幂函数。

文章介绍了在SQLite单一文件中存储、FTS5+矢量检索的混合化、基于RRF的综合、时间衰减评分等设计思想。fuga-memory是以这些想法为出发点，加上Python+fastmcp的实施、安全性强化、设定的灵活化等独自的实施。

感谢noprogllama先生公开了优秀的设计思想。

______________________________________________________________________

许可证

麻省理工学院