商业产业 Hacker News Agent 2026-08-13T13:57 正文 ok 1011 words

Show HN：MCP Memory——利用 Google OKF 与 SQLite FTS5 实现高速 Agent 记忆

英文标题：🔶 Show HN: MCP Memory – Fast Agent Memory Using Google's OKF and SQLite FTS5

MCP-Memory 是一款 Model Context Protocol（MCP）服务器，为 Claude Desktop、Cursor、Antigravity、Windsurf 和 Codex 等 AI Agent 提供跨会话的持久化长期记忆。它以 Open Knowledge Format（OKF v0.2）Markdown 文件保存记忆，并通过本地 SQLite FTS5 索引实现键值查询、标签筛选和全文搜索，项目称键查询延迟可低于 20ms。该工具提供记忆写入、读取、搜索及会话检查点机制，并可借助安装向导自动配置多种 MCP 客户端。对开发者而言，其意义在于以可审阅的本地 Markdown 文件与高性能数据库索引相结合的方式，为 Agent 构建项目隔离、可追溯且易迁移的记忆层。

打开原文相关 6 · 机会 2

125.7 KB

中文

MCP-Memory：由 OKF 支持的 Agent 记忆服务器

MCP-Memory 是一款 Model Context Protocol（MCP）服务器，可为 AI Agent（例如 Claude Desktop、Cursor、Antigravity、Windsurf 或 Codex）提供持久化的长期记忆能力。

记忆记录采用 开放知识格式（Open Knowledge Format，OKF v0.2） 标准进行格式化，并通过本地 SQLite 实例建立索引（支持 FTS5 全文搜索），以实现快速键值查询、标签筛选和内容搜索。

**快速通道：**直接跳转至快速开始

**跨会话持久状态：**允许 AI Agent 读取、存储、搜索和删除可跨聊天轮次及会话持久存在的状态化记忆片段。
**符合 OKF 标准：**每项记忆均以 OKF v0.2 Markdown 文档形式存储，包含 YAML 前置元数据（type、key、namespace、tags、generated、sources、verified、status、stale_after），并严格遵循 SPEC.md 和 OKF_RULES.md。
双层架构：
- **可供人工浏览的 OKF 目录：**自动将每项记忆导出并同步至磁盘，在 memory/ 包目录中保存为原始 .md 文件；同时提供层级化的 index.md 渐进式披露文件（根 index.md 使用 okf_version: "0.2" 进行版本标记）以及用于跟踪更新历史的 log.md。
- **高性能 SQLite 索引：**借助 SQLite FTS5（全文搜索）和自动触发器，实现低于 20ms 的键查询及即时关键词搜索。
**命名空间隔离：**支持上下文隔离（例如 user/preferences、project/architecture、default）。
**零样板配置：**快速设置向导（python3 setup.py）可自动配置已安装的 MCP 工具（Antigravity、Claude、Cursor、Windsurf、Codex）。

服务器向交互 Agent 暴露四项主要 MCP 工具：

以 OKF v0.2 格式存储或更新一条记忆记录。

参数：
- key （字符串，必填）：记忆的唯一标识符或路径（例如 user/preferences/coding_style 或 project/architecture）。
- content （字符串或对象，必填）：要存储的核心信息。
- project_root （字符串，必填）：当前项目根目录的绝对路径（例如 /Users/user/Projects/my-app）。
- tags （字符串数组，可选）：用于筛选的分类标签。
- namespace （字符串，可选，默认值："default"）：作用域/命名空间。
- concept_type （字符串，可选，默认值："Agent Memory"）：OKF 概念类型（例如 Metric、Playbook、Attested Computation）。
- title （字符串，可选）：显示名称。
- description （字符串，可选）：单行摘要。
- resource （字符串，可选）：底层资产的规范 URI。
- status （字符串，可选，默认值："stable"）：生命周期状态（draft | stable | deprecated）。
- stale_after （字符串，可选）：ISO 日期（YYYY-MM-DD）。
- sources （对象数组，可选）：来源追溯信息 [{resource, id, title, author, usage_count, last_modified}]。
- verified （对象数组或对象，可选）：验证事件 [{by, at}]。
- generated_by （字符串，可选）：遵循 Actor 约定的行为者标识符（<producer>/<version>、human:<id>、process:<id>）。

通过键和命名空间检索特定记忆。

参数：
- key （字符串，必填）：要查询的记忆键。
- project_root （字符串，必填）：当前项目根目录的绝对路径。
- namespace （字符串，可选，默认值："default"）：作用域/命名空间。

查找与关键词、标签或命名空间筛选条件匹配的记忆。

参数：
- project_root （字符串，必填）：当前项目根目录的绝对路径。
- query （字符串，可选）：对键、前置元数据和内容进行关键词搜索的查询语句。
- tags （字符串数组，可选）：按特定标签筛选。
- namespace （字符串，可选）：将搜索限定在某一命名空间内。
- limit （整数，可选，默认值：10）：最大结果数量。

**AGENT 指令（会话开始）：**检索最后记录的会话检查点（system/last_memory），以便 AI Agent 在打开项目或开始会话时立即获知工作上次停留的位置。

参数：
- project_root （字符串，必填）：当前项目根目录的绝对路径。
- namespace （字符串，可选，默认值："default"）：作用域/命名空间。

**AGENT 指令（里程碑与进度）：**在完成里程碑、进行关键变更或暂停工作时更新规范会话检查点（system/last_memory）。

参数：
- content （字符串或对象，必填）：简短说明或结构化字典，用于汇总进度并引用关键记忆文件。
- project_root （字符串，必填）：当前项目根目录的绝对路径。
- namespace （字符串，可选，默认值："default"）：作用域/命名空间。
- summary （字符串，可选）：对达成里程碑的一句话描述。

OKF（开放知识格式）结构

每条已存储记忆都严格遵循 OKF v0.2 规范（SPEC.md 与 OKF_RULES.md）：

---
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.

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

2. 交互式设置向导

运行 setup.py，以自动检测并向 AI 工具注册 mcp-memory：

注意：setup.py 完成工具配置后，AI 客户端会在需要时自动于后台启动 mcp-memory。你无需在终端中手动启动或持续运行服务器进程。

3. 通过 CLI 手动运行（可选 / 用于调试）

如需手动验证启动、检查 stdio 输出，或预先初始化虚拟环境（.venv），可直接运行 run.sh：

手动客户端配置

如果你希望手动配置 MCP 客户端，请添加指向 run.sh 的 "memory" 服务器条目：

JSON 配置（Antigravity、Claude Desktop、Cursor、Windsurf）

添加至客户端的 mcp_config.json 或 claude_desktop_config.json：

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

TOML 配置（Codex Desktop）

添加至 ~/.codex/config.toml：

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

Claude Code CLI：

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

Codex CLI：

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

运行自动化测试套件，以验证 OKF 序列化、SQLite 数据库操作和 FastMCP 工具执行：

存储与环境变量

默认情况下，mcp-memory 会在每个项目的根目录内创建项目隔离的记忆存储：

**OKF Markdown 文件（人类可读）：**项目根目录中的 memory/ 文件夹。
**SQLite 数据库（隐藏索引）：**项目根目录中的 .mcp_memory/memories.db。

你可以使用环境变量自定义这一行为：

MCP_MEMORY_PROJECT_ROOT：项目根目录（默认值：进程当前工作目录 cwd）。
MCP_MEMORY_DB_PATH：SQLite 数据库文件路径（默认值：相对于项目根目录的 .mcp_memory/memories.db）。
MCP_MEMORY_DIR：用于存放开放知识格式（OKF）.md 文件的目录（默认值：相对于项目根目录的 memory）。

**提示：**如果希望在所有项目之间共享单一的全局记忆存储，可在客户端的 MCP 配置中设置 MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db 和 MCP_MEMORY_DIR=~/.mcp_memory/memory。

English / 原文

MCP-Memory: OKF-Backed Agent Memory Server

MCP-Memory is a Model Context Protocol (MCP) server that equips AI agents (such as Claude Desktop, Cursor, Antigravity, Windsurf, or Codex) with persistent, long-term memory capabilities.

Memory records are formatted using the Open Knowledge Format (OKF v0.2) standard and indexed with a local SQLite instance (supporting FTS5 full-text search) for fast key-value lookups, tag filtering, and content search.

Fast Track: Jump directly to Quick Start

Persistent State Across Sessions: Enables AI agents to read, store, search, and delete stateful memory snippets that persist across chat turns and sessions.
OKF Standard Compliance: Stores every memory item formatted as an OKF v0.2 Markdown document with YAML frontmatter (type, key, namespace, tags, generated, sources, verified, status, stale_after), adhering strictly to SPEC.md and OKF_RULES.md.
Dual-Layer Architecture:
- Human-Browseable OKF Directory : Automatically dumps and syncs every memory to disk as a raw .md file inside the memory/ bundle directory with hierarchical index.md progressive disclosure files (root index.md versioned with okf_version: "0.2") and log.md update history tracking.
- High-Performance SQLite Indexing : SQLite FTS5 (Full-Text Search) and automatic triggers for sub-20ms key lookups and instant keyword searches.
Namespace Isolation: Supports contextual separation (e.g. user/preferences, project/architecture, default).
Zero Boilerplate Setup: Quick setup wizard (python3 setup.py) auto-configures installed MCP tools (Antigravity, Claude, Cursor, Windsurf, Codex).

The server exposes four primary MCP tools to interacting agents:

Stores or updates a memory record in OKF v0.2 format.

Parameters:
- key (string, required) : Unique identifier or path for the memory (e.g. user/preferences/coding_style or project/architecture).
- content (string or object, required) : Core information to store.
- project_root (string, required) : Absolute path to the active project root directory (e.g. /Users/user/Projects/my-app).
- tags (array of strings, optional) : Classification tags for filtering.
- namespace (string, optional, default:"default"): Scope/namespace.
- concept_type (string, optional, default:"Agent Memory"): OKF concept type (e.g. Metric, Playbook, Attested Computation).
- title (string, optional) : Display name.
- description (string, optional) : One-line summary.
- resource (string, optional) : Canonical URI of underlying asset.
- status (string, optional, default:"stable"): Lifecycle state (draft | stable | deprecated).
- stale_after (string, optional) : ISO date (YYYY-MM-DD).
- sources (array of objects, optional) : Provenance sources [{resource, id, title, author, usage_count, last_modified}].
- verified (array of objects or object, optional) : Verification events [{by, at}].
- generated_by (string, optional) : Actor identifier following actor convention (<producer>/<version>, human:<id>, process:<id>).

Retrieves a specific memory by its key and namespace.

Parameters:
- key (string, required) : The memory key to look up.
- project_root (string, required) : Absolute path to the active project root directory.
- namespace (string, optional, default:"default"): Scope/namespace.

Finds memories matching keywords, tags, or namespace filters.

Parameters:
- project_root (string, required) : Absolute path to the active project root directory.
- query (string, optional) : Keyword search query across keys, frontmatter, and content.
- tags (array of strings, optional) : Filter by specific tags.
- namespace (string, optional) : Scope search to a namespace.
- limit (integer, optional, default: 10) : Maximum number of results.

AGENT DIRECTIVE (Session Start): Retrieves the last recorded session checkpoint (system/last_memory) so the AI agent immediately knows where work was left off when opening a project or starting a session.

Parameters:
- project_root (string, required) : Absolute path to active project root directory.
- namespace (string, optional, default:"default"): Scope/namespace.

AGENT DIRECTIVE (Milestones & Progress): Updates the canonical session checkpoint (system/last_memory) whenever completing a milestone, making key changes, or pausing work.

Parameters:
- content (string or object, required) : Brief note or structured dictionary summarizing progress and referencing key memory files.
- project_root (string, required) : Absolute path to active project root directory.
- namespace (string, optional, default:"default"): Scope/namespace.
- summary (string, optional) : One-sentence description of the milestone achieved.

OKF (Open Knowledge Format) Structure

Every stored memory strictly adheres to the OKF v0.2 specification (SPEC.md & OKF_RULES.md):

---
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.

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

2. Interactive Setup Wizard

Run setup.py to auto-detect and register mcp-memory with your AI tools:

Note: Once setup.py finishes configuring your tools, your AI client will launch mcp-memory automatically in the background whenever needed. You do not need to manually start or keep a server process running in your terminal.

3. Run Manually via CLI (Optional / Debugging)

If you want to manually verify startup, inspect stdio output, or pre-initialize the virtual environment (.venv), you can run run.sh directly:

Manual Client Configuration

If you prefer to configure your MCP client manually, add the "memory" server entry pointing to run.sh:

JSON Configuration (Antigravity, Claude Desktop, Cursor, Windsurf)

Add to your client's mcp_config.json or claude_desktop_config.json:

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

TOML Configuration (Codex Desktop)

Add to ~/.codex/config.toml:

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

Claude Code CLI:

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

Codex CLI:

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

Run the automated test suite to verify OKF serialization, SQLite database operations, and FastMCP tool execution:

Storage & Environment Variables

By default, mcp-memory creates project-isolated memory stores inside each project's root directory:

OKF Markdown Files (Human-readable) : memory/ folder in project root.
SQLite Database (Hidden index) : .mcp_memory/memories.db in project root.

You can customize this behavior using environment variables:

MCP_MEMORY_PROJECT_ROOT: Project root directory (default: process current working directory cwd).
MCP_MEMORY_DB_PATH: SQLite database file path (default: .mcp_memory/memories.db relative to project root).
MCP_MEMORY_DIR: Directory for Open Knowledge Format (OKF) .md files (default: memory relative to project root).

Tip: If you prefer a single global memory store shared across all projects, set MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db and MCP_MEMORY_DIR=~/.mcp_memory/memory in your client's MCP configuration.