MCP-Memory: 使用 OKF 與 SQLite FTS5 的快速 Agent 記憶體

快速概覽

MCP-Memory 提供 AI agent 提供符合 OKF‑v0.2 標準的持久化記憶，並透過本地 SQLite FTS5 資料庫進行索引，在提供低於 20 ms 的鍵值查詢與即時全文檢索的同時，也保留了人類可瀏覽的 Markdown 目錄。

什麼是 MCP-Memory

MCP-Memory 是一個 Model Context Protocol (MCP) server，為 Claude Desktop、Cursor、Antigravity、Windsurf 或 Codex 等 agent 提供長期且可搜尋的記憶。每一筆記憶記錄都以帶有豐富 YAML front‑matter 的 OKF v0.2 markdown 文件形式儲存，且相同的數據會被索引在 SQLite FTS5 中以實現快速檢索。

核心設計選擇

雙層架構

人類可瀏覽的 OKF 目錄 – 每一筆記憶都會以 .md 文件形式 dump 到 memory/ 目錄下，並配有層級化的 index.md 文件，提供了一個版本化且可讀的知識庫。
高效能 SQLite 索引 – 使用帶有 FTS5 觸發器的 SQLite 資料庫，可實現低於 20 ms 的鍵值查詢以及跨鍵值、front‑matter 與內容的關鍵字搜尋。

命名空間隔離

記憶可以按命名空間（例如 user/preferences、project/architecture、default）進行分割，防止跨專案的數據污染。

零樣板代碼設定

執行 python3 setup.py 會自動偵測支援的 agent 並註冊 memory MCP server，因此 agent 啟動時會自動啟動 server，無需持續性的 terminal 處理程序。

MCP Tools Exposed to Agents

Tool	Purpose	Key Parameters
`memory_store`	建立或更新記憶記錄	`key`, `content`, `project_root`, optional `tags`, `namespace`, `concept_type`, `title`, `description`, `resource`, `status`, `stale_after`, `sources`, `verified`, `generated_by`
`memory_retrieve`	透過鍵值獲取單一記錄	`key`, `project_root`, optional `namespace`
`memory_search`	全文檢索或基於標籤的搜尋	`project_root`, optional `query`, `tags`, `namespace`, `limit`
`memory_get_last`	啟動時獲取最近一次會話的檢查點 (`system/last_memory`)	`project_root`, optional `namespace`
`memory_update_last`	在里程碑之後更新檢查點	`content`, `project_root`, optional `namespace`, `summary`

OKF v0.2 Specification in Practice

每一筆記憶都遵循 OKF front‑matter schema，例如：

---
type: Agent Memory
title: Coding Style
key: user/preferences/coding_style
namespace: default
tags:
  - preferences
  - style
status: stable
generated:
  by: mcp-memory/0.2.0
  at: '2026-08-12T19:23:35Z'
created_at: '2026-08-12T19:23:35Z'
updated_at: '2026-08-12T19:23:35Z'
---
User prefers functional programming style with explicit type annotations.

相同的檔案會存在於 memory/ 中，而其可搜尋的表示形式則儲存在 .mcp_memory/memories.db。

Installation & Quick Start

Clone 儲存庫：

git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory

Run the setup wizard 以自動註冊 server 與支援的 agents：
```
python3 setup.py
```
完成後 agent 將會根據需求啟動 mcp-memory。
Optional manual start 用於除錯：
```
./run.sh
```

Manual Client Configuration

如果你偏好明確的配置，可以添加一個指向 run.sh 的 memory 項目：

JSON (Antigravity, Claude Desktop, Cursor, Windsurf)

{
  "mcpServers": {
    "memory": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

TOML (Codex Desktop)

[mcp_servers.memory]
command = "/ABSOLUTE/PATH/TO/run.sh"

CLI examples

claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh

Storage Layout & Environment Variables

OKF markdown – memory/ 目錄位於專案根目錄下。
SQLite index – .mcp_memory/memories.db (隱藏目錄)。
環境變數允許自定義位置：
- MCP_MEMORY_PROJECT_ROOT – 預設為當前工作目錄。
- MCP_MEMORY_DB_PATH – 預設為 .mcp_memory/memories.db。
- ``MCP_MEMORY_DIR– 預設為memory`。
若要跨專案共享單一儲存庫，請設置 MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db 且 MCP_MEMORY_DIR=~/.mcp_memory/memory。

Community Feedback Highlights

@myshapeprotocol – “使用 SQLite FTS5 進行快速 agent 記憶是如此實用的工程設計選擇。很棒的 Show HN 專案。”

@bearjaws – “又一週，又一個 agent 記憶系統，其功能與在 memory/ 目錄下使用 grep 幾乎一樣。”

@healthycoder – “這與我們現有的所有其他 Memory 相關工具（如 mem0 等）有什麼不同？它們做的是同樣的事情。”

@jrflo – “為什麼這比直接使用 markdown 檔案並讓 agent 使用 grep 有益？我發現 MCP tools 可以讓 agent 變慢並浪費 token。”

@FitchApps – “你能為新手解釋一下，為什麼要使用 Google 的 OKF 格式而不是純粹的 MD 檔案嗎？”

@rcarmo – “很高興看到更多基於 OKF 的方法。我的專案是 https://rcarmo.github.io/projects/memento/.”

這些評論反映了兩個重複出現的主題：結構化 OKF 元數據的價值與純粹的 markdown 檔案相比，以及與簡單的 grep 相比的 SQLite 索引效能權衡。

How MCP-Memory Differs from Existing Solutions

Standardized metadata – OKF v0.2 強制執行統一的 schema（type, tags, status, provenance），這點是純粹的 markdown 檔案所缺乏的，從而實現了更豐富的過濾與自動化生命週期管理。
Sub‑20 ms indexed lookups – SQLite FTS5 提供確定性的延遲，而 grep 的效能會隨著檔案大小線性增長，在大型專案中可能會成為瓶頸。
Dual persistence – Agents 獲得了透過資料庫進行即時的機器可讀取存取，同時開發者保留了人類可讀的 markdown 檔案存檔，便於檢視與版本控制。
Namespace isolation – 內建支援分割不同的知識領域，防止了不相關專案之間的意外數據污染。

When to Use MCP-Memory

專案需要對數十到數千個知識片段進行 快速、確定性的檢索。
團隊想要 可審計性：markdown 目錄可以進行版本控制，而資料庫則驅動 agent。
工作流程中受益於 結構化來源證明 (provenance)（來源、驗證、狀態）以符合合規性或文件化需求。

Limitations & Open Questions

沒有內建的向量搜尋 (vector search)；記憶僅透過精確的鍵值、標籤或全文檢索來獲取。
效能增益依賴於 SQLite 的 FTS5 配置；極大型的語料庫可能仍需進行分片 (sharding)。
有些用戶回報，如果 agent 反覆多次查詢 server，MCP tooling 可以增加 token 消耗；因此需要謹慎設計 prompt。

Conclusion

MCP-Memory 透過結合 Google 的 Open Knowledge Format 與 SQLite FTS5，彌補了人類可讀的知識庫與高效能 agent 記憶之間的差距。其雙層架構、命名空間隔離與零樣板代碼設定，使其成為開發者尋於求結構化、快速且持久化 context 供 AI agent 使用的開發工具。