A
licenseNot graded
qualityD
maintenanceMCP server providing persistent memory management for AI agents using SQLite and FTS5, enabling storage, full-text search, and recall of memories with namespace isolation.
1
MIT
fuga-memory
by densuke
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fuga-memorysearch memory for Python asyncio notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fuga-memory
Claude Code（および他の LLM）向け長期記憶 MCP サーバー。
会話内容を SQLite に保存し、FTS5（全文検索）+ ベクトル検索（ruri-v3-310m）のハイブリッド検索で関連する記憶を呼び出します。
特徴
外部依存なし: 全データを SQLite 単一ファイルに格納
ハイブリッド検索: FTS5 キーワード検索 + ベクトル検索を RRF で統合
時間減衰: 古い記憶のスコアを半減期 30 日で段階的に低下
軽量推論: ONNX バックエンドで ruri-v3-310m を CPU で動作
MCP 対応: Claude Code / Gemini / Copilot など複数 LLM で共有可能
自動保存: Claude Code の Stop フックでセッション終了時に自動保存
Related MCP server: tartarus-mcp
セットアップガイド
クイックスタート
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回目以降は高速に起動します。
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.toml3. 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 transport で動作します。
Claude Code ←─ stdin/stdout ─→ fuga-memory serve (子プロセス)ポイント:
Claude Code が
mcpServersの設定を読み、必要に応じて自動でプロセスを起動・停止します常駐サーバーを手動で立ち上げておく必要はありません
HTTP ポートも使用しません
Stop フックでの自動保存の仕組み
セッション終了
↓
Claude Code が Stop フックを実行
↓
fuga-memory save --stdin --session-id <id> （短命な1回限りのプロセス）
↓
SQLite に保存完了Stop フックは MCP サーバーとは独立して動作します。フックが走るときに MCP サーバーが起動している必要はありません。
Claude Code での使い方
MCP ツールが有効になると、以下の 3 つのツールが使えるようになります。
save_memory — 記憶を保存
save_memory(content="今日Pythonのasyncioを勉強した", session_id="my-session")引数 | 型 | 説明 |
| str | 保存するテキスト（必須） |
| str | セッション識別子（必須） |
| str | ソース識別子（デフォルト: |
search_memory — 記憶を検索
search_memory(query="Pythonの非同期処理", top_k=5)引数 | 型 | 説明 |
| str | 検索クエリ（必須） |
| int | 返す最大件数（デフォルト: 5） |
返り値: [{"id", "score", "content", "session_id", "source", "created_at"}, ...]（score 降順）
list_sessions — セッション一覧
list_sessions(limit=20)返り値: [{"session_id", "memory_count", "last_updated"}, ...]
CLI リファレンス
MCP 経由ではなく、コマンドラインから直接操作できます。
serve — MCP サーバーを起動
uv run fuga-memory serve
uv run fuga-memory --debug serve # ライブラリ警告を抑制しないデバッグモード通常は手動で起動する必要はありません。Claude Code が自動で管理します。 他の MCP クライアント（Gemini CLI 等）と接続する場合や動作確認時に使用します。
search — 記憶を検索
uv run fuga-memory search "Rustのlifetimeについて"
uv run fuga-memory search "Python" --top-k 10save — 記憶を保存
3 種類の入力方式があります。
# 引数として直接渡す
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 |
|
2 | Linux / 共通 |
|
3 | 共通 |
|
テンプレートから作成:
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 など、ファイル配置が難しい環境向けです。
変数 | デフォルト | 説明 |
|
| DB ファイルパス |
|
| 埋め込みモデル |
| CPU 数 ÷ 2 | 推論スレッド数 |
|
| RRF の k パラメータ |
|
| 時間減衰の半減期（日） |
|
| デフォルト検索件数 |
|
| デーモンの待ち受けポート |
|
| デーモンのアイドル自動終了（秒） |
|
| ONNX キャッシュディレクトリ |
|
| デバッグモード（警告を抑制しない） |
詳細は .env.example を参照してください。
優先順位
デフォルト値 < 設定ファイル < 環境変数データの場所
項目 | デフォルトパス |
DB ファイル |
|
ONNX キャッシュ |
|
モデルキャッシュ |
|
DB ファイルは 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 バックエンド）
ThreadPoolExecutor + asyncio
インスピレーション
このプロジェクトは、noprogllama 氏による Zenn 記事
Claude Codeに長期記憶を持たせたら、壁打ちの質が変わった
にインスパイアされて開発しました。
同記事では、SQLite 単一ファイルへの格納、FTS5 + ベクトル検索のハイブリッド化、RRF による統合、時間減衰スコアリングといった設計思想が紹介されています。fuga-memory はこれらのアイデアを出発点として、Python + fastmcp による実装、セキュリティ強化、設定の柔軟化などを加えた独自の実装です。
優れた設計思想を公開してくださった noprogllama 氏に感謝します。
ライセンス
MIT
Available Tools
4 toolsdelete_memoryA
記憶を削除する。
Args: memory_id: 削除する記憶の ID（1 以上）。
Returns: {"status": "deleted"}
Raises: ValueError: memory_id が 1 未満の場合、または指定された ID の記憶が見つからない場合。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It mentions error conditions (ValueError) and the return format, but does not explicitly state that the operation is destructive and irreversible. The risk is partially covered by the error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with separate sections for Args, Returns, and Raises. It is concise, but the Japanese text may reduce clarity for non-Japanese users. The information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single required parameter, no nested objects) and the existence of an output schema, the description covers the essential behavior, error conditions, and return value. It is complete for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'memory_id' as an integer with no description (0% coverage). The description adds clear meaning: the ID must be 1 or greater, and it is the identifier of the memory to delete. This compensates well for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete memory') and the resource (memory). It is distinct from sibling tools like save_memory, search_memory, and list_sessions, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use delete_memory versus other tools. It only describes the technical behavior without contextualizing its role in a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_sessionsA
セッション一覧を返す（直近更新順）。
エンコーダ不要の読み取り専用操作のため、モデルの初期化を発生させない。
Args: limit: 返す最大件数（デフォルト: 20、1 以上）。
Returns: [{"session_id", "memory_count", "last_updated"}, ...]
Raises: ValueError: limit が 1 未満または 200 超の場合。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It states the tool is read-only, does not trigger model initialization, returns results sorted by last update, and raises ValueError for invalid limit values. This provides clear behavioral expectations beyond the schema, though additional details like pagination or response structure are already given in Returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured (Args, Returns, Raises). Every sentence serves a purpose—purpose, behavior, parameter guidance, error info. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no required params, output schema in description), the description fully covers purpose, usage, constraints, error handling, and return format. Sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description adds meaning by explaining the 'limit' parameter: maximum number to return (default 20, must be >=1) and that ValueError is raised if limit is <1 or >200. This covers constraints and error handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'セッション一覧を返す（直近更新順）', meaning 'Returns list of sessions (most recently updated first)'. It specifies the verb (返す/returns), resource (セッション一覧/list of sessions), and sorting order, distinguishing it from sibling tools like save_memory, search_memory, and delete_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that this is a read-only operation that does not cause model initialization, guiding when to use it for safe, lightweight queries. However, it does not explicitly mention when not to use it or compare with siblings, though the context signals indicate it is distinct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
save_memoryA
記憶を保存する。
Args: content: 保存するテキスト（1文字以上、100,000文字以下）。 session_id: セッション識別子。 source: 記憶のソース（デフォルト: "manual"）。
Returns: {"id": int, "status": "saved"}
Raises: ValueError: content が空または上限を超えた場合。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | manual | |
| content | Yes | ||
| session_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that content must be 1-100,000 characters and raises ValueError if invalid. It also specifies the return format. However, it does not mention if the operation is idempotent, whether it overwrites existing data, or any authentication requirements. Given no annotations, this is adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections for Args, Returns, and Raises. Every sentence adds value, and the format is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple save tool with three parameters and no nested objects, the description covers the input constraints, default values, and output format. It lacks details on whether session_id must pre-exist or if the tool overwrites, but overall it is sufficiently complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description compensates by explaining each parameter: content (text with length constraints), session_id (identifier), and source (default 'manual'). This adds meaningful context beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Save memory' (保存する) with specific arguments for content, session_id, and source. It distinguishes itself from sibling tools like search_memory, list_sessions, and delete_memory by focusing on saving a new memory entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It only describes the tool's function without mentioning prerequisites or when not to use it. The sibling names imply distinct operations, but no direct comparison is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_memoryA
ハイブリッド検索（FTS + ベクトル + RRF + 時間減衰）。
Args: query: 検索クエリ文字列。 top_k: 返す最大件数（デフォルト: 5、1 以上）。
Returns: [{"id", "score", "content", "session_id", "source", "created_at"}, ...] score の降順でソート済み。
Raises: ValueError: query が 4,096 文字を超える場合、top_k が 1 未満または 100 超の場合。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden. It details the hybrid search method, time decay, score ordering, and exact exceptions (ValueError for invalid parameters). It does not mention read-only nature or side effects, but the context (search) implies no mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using structured Markdown sections (Args, Returns, Raises). It front-loads the core hybrid search concept and uses minimal sentences with maximum information, leaving no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (hybrid search with multiple techniques and time decay), the description covers all essential aspects: input parameters, output format with fields and sorting, and error conditions. The output schema exists and is described, so return values are fully documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains 'query' as search query string and 'top_k' as max results with default and range. Additionally, it specifies validation constraints (top_k 1-100, query max 4096) and errors, adding significant semantic value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies 'hybrid search (FTS + vector + RRF + time decay)' stating the verb (search) and resource (memory). It distinguishes from sibling tools by naming the specific search technique, which is unique among save, list, and delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for searching memories but does not explicitly state when to use this tool versus siblings (save_memory, list_sessions, delete_memory). It lacks exclusion criteria or alternative suggestions, relying on tool names for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
A4/5.0
Disambiguation5/5
Each tool has a clearly distinct purpose: save, search, list sessions, and delete. No overlap or ambiguity in their functionalities.
Naming Consistency5/5
All tool names follow the consistent verb_noun pattern (save_memory, search_memory, list_sessions, delete_memory), enhancing predictability.
Tool Count4/5
With 4 tools, the set is slightly minimal but covers core memory operations. A few more tools like update or get-by-id could be added, but the current count is reasonable for the domain.
Completeness3/5
Missing update and direct retrieval by ID are notable gaps; however, search serves as a retrieval mechanism. The surface covers create, read (via search), and delete, with list_sessions providing session management.
Maintenance
ActivityInactive
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Cloud-hosted MCP server for durable AI memory
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Persistent memory for AI agents — log and recall conversation context over MCP.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local-first MCP memory server providing persistent, searchable memory for AI agents, powered by SQLite.61Apache 2.0
- FlicenseNot gradedqualityDmaintenanceAn MCP server for managing persistent AI memory using hybrid search (keyword + semantic vector) with SQLite storage and offline-first local embeddings.
- AlicenseAqualityCmaintenancePersistent memory MCP server for AI agents, using SQLite with hybrid keyword and semantic search for long-term memory storage.5Do What The F*ck You Want To Public
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/densuke/fuga-memory'
If you have feedback or need assistance with the MCP directory API, please join our Discord server