Fraise

Fraise

文档 · Discord · 查询语言 · 问题

**Fraise 是面向 AI Agent 的记忆数据库。**它们可以直接查询，使用专为令牌而非人类设计的语言。

remember 'acme moved to annual billing' topic:billing entity:acme

recall billing entity:acme since:30d top:5

两个动词。一个二进制文件。无需运行任何基础设施。

安装

brew install fraisehq/tap/fraise
brew services start fraise
curl -X POST localhost:9876/api/v1/q -H 'content-type: application/json' \
  -d "{\"query\": \"remember 'the parrot is turquoise' topic:color\"}"

Linux 软件包、Docker、go install 和已签名的发行版二进制文件均可在下方的快速入门中找到。

部署前请阅读持久性。持久化功能对应 issue #171，也是下一项主要工作。

对比情况

在 LoCoMo 上测得——包含 10 段多轮对话和 1,986 个问题——所有系统摄取相同的对话，使用相同的提取模型和嵌入模型，并回答相同的问题。k=10，完整数据；每个系统截至 2026-10-11 的最新一次运行。

系统	检索召回率	p50 搜索耗时	记忆令牌数
fraise 0.3.3	0.910	0.185 s	7,453,109
hindsight 0.9.2	0.913	5.836 s	1,688,873
everos 1.2.3	0.897	0.376 s	10,030,966
letta 0.16.8	0.897	0.349 s	226,854
mem0 2.0.18	0.886	0.576 s	4,120,078
memos 2.0.33	0.865	0.307 s	4,000,552
graphiti 0.30.2	0.828	0.290 s	9,861,973
cognee 1.5.3	0.790	6.273 s	8,526,019
langmem 0.0.30	0.783	0.227 s	1,078,110

**Fraise 的召回率与最佳成绩仅差 0.003，速度却比达到该成绩的唯一系统快 31 倍。**证据几乎相同，耗时却少得多。令牌数列反映了获得这种召回率的代价：提取器（fraise-sdk 0.2.0）会在读取每条消息时，同时参考图谱中已有的内容，召回率正是由此而来。

这些数据来自 agent-memory-benchmarks，这是一个开放的测试框架——按 k ∈ {1, 3, 5, 10} 统计精确率、召回率和 F1，并按类别细分；每次运行都有标签，可根据标签复现。完整表格见其 RESULTS.md。

Fraise 的优势

• **Agent 真正能写的查询语言。**FQL 只有两个动词——remember 和 recall——每件事也只有一种表达方式。自由度更少，模型出错的方式就更少，表达所需的令牌也更少。
• **混合检索。**事实会建立索引，支持全文、图谱和（可选的）向量搜索。一次查询即可跨三种方式进行排序。
• **默认考虑时间因素。**近期记忆的优先级高于较早的记忆，因此无需特别指定，召回就会考虑时效性。
• **实测最快的系统。**在 LoCoMo 上的 p50 为 0.185 s，领先所有其他系统，速度比召回率相当的系统快 31 倍。用户等待时，也能在步骤执行期间记忆和召回。
• **无需基础设施。**只需一个二进制文件。无需配置数据库，也无需额外运行配套服务。
• 开源，采用 MIT 许可证。

状态

**v0.3.3。**核心循环已端到端跑通，安装流程也已在全新机器上验证。上面的基准测试数据来自此版本。0.4.0（10 月下旬）将更改评分器，并添加 explain 和 describe；0.5.0（11 月）将支持持久化和 forget。

如今适合用于构建 Agent 记忆。暂不适合长期投入生产使用。

工作原理

Fraise 将知识存储为时序记忆图，由三种节点构成：

• 事实——记忆的内容，每条陈述各占一条
• 实体——事实中提及的人或事物
• 主题——事实所涉及的内容

边将事实连接到其中提及的实体和涉及的主题，因此查询可以从任一侧开始。recall 会通过文本以及（可选的）向量相似度查找种子事实；如果一次 recall 只指定主题或实体，则从归档在这些主题或实体下的事实开始。使用 depth:1 或 depth:2 时，如果某个指定主题或实体所匹配的事实表现优于其规模所预期的水平，就会将这份证据传递给它的其余事实。结果按相关性和新近程度排序，并返回排名最高的 top 条。

排序并非黑箱：事实的得分由自身的匹配强度，以及从锚点传递过来的分值构成；只有当锚点承载的权重高于其规模所预期的水平时，才会传递分值。衡量“高于”的基准率会根据查询触及的图谱部分，针对每次查询单独估算，因此无需调整相关性常数。混合检索介绍了完整模型。

单个 Fraise 实例可容纳多个彼此独立的记忆图（默认 8 个），通过 @N 寻址——可以为每位用户、每个会话或每个 Agent 各建一个，按你的需要设置。

快速开始

Fraise 是一个单独的二进制文件——无需配置数据库，也无需进行任何设置。以下每种方式启动后，都会让服务在 localhost:9876 的 9876 端口上监听。

使用 Homebrew

brew install fraisehq/tap/fraise
brew services start fraise

服务可在崩溃后自动恢复，并在登录时启动（keep_alive）；日志写入 $(brew --prefix)/var/log/fraise.log，配置文件位于 $(brew --prefix)/etc/fraise/fraise.config.toml——安装时会将每项设置都注释掉并设为默认值，升级时也不会覆盖该文件。

使用 Docker

docker run -p 127.0.0.1:9876:9876 ghcr.io/fraisehq/fraise:latest

发布的标签包括：每个版本一个标签、最新稳定版使用 latest、main 分支最新提交使用 edge，以及每次涉及服务端的合并所对应的不可变完整提交 SHA 标签。

镜像使用 SLSA provenance 构建，无需拉取即可验证：

gh attestation verify oci://ghcr.io/fraisehq/fraise:latest --repo FraiseHQ/fraise

使用 Go

go install github.com/FraiseHQ/fraise/cmd/server@latest
"$(go env GOPATH)/bin/server"

二进制文件安装后名为 server，名称取自其包路径——如果你觉得 fraise 更顺口，可以将它重命名。

无需其他操作即可信任这个二进制文件：Go 工具链会通过公开的校验和透明日志验证每次模块下载，并由你自己的计算机编译结果。

Linux 软件包

每个版本都会提供 .deb 和 .rpm 软件包，并附带 systemd 用户单元：

VERSION=0.3.0
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -sSfLO "https://github.com/FraiseHQ/fraise/releases/download/v${VERSION}/fraise_${VERSION}_linux_${ARCH}.deb"
sudo dpkg -i "fraise_${VERSION}_linux_${ARCH}.deb"
systemctl --user enable --now fraise

日志写入 journal（journalctl --user -u fraise -f）。如果存在 ~/.config/fraise/fraise.config.toml，该单元会读取此文件；随软件包提供的默认配置文件位于 /etc/fraise/fraise.config.toml，其中每项设置都已注释，可供复制。若希望 Agent 在你注销后继续运行，可让用户管理器持续运行：loginctl enable-linger $USER。在作为受管理服务运行中介绍了 system 级（共享服务器）版本的单元。

使用发布版二进制文件

VERSION=0.3.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')                # linux | darwin
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')  # amd64 | arm64
ASSET="fraise_${VERSION}_${OS}_${ARCH}.tar.gz"
BASE="https://github.com/FraiseHQ/fraise/releases/download/v${VERSION}"

curl -sSfLO "${BASE}/${ASSET}"
tar xzf "$ASSET"
./fraise

Windows 版本采用相同的命名方案，以 .zip 文件形式发布。

验证发布版本

发布版本附带对 checksums.txt 的 cosign 签名，使用与上文相同的 VERSION 和 BASE：

curl -sSfLO "${BASE}/checksums.txt"
curl -sSfLO "${BASE}/checksums.txt.sigstore.json"

# 1. the bundle proves checksums.txt came from this repo's release workflow
cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/FraiseHQ/fraise/.github/workflows/go.yaml@refs/tags/v.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

# 2. checksums.txt proves your archive is the one it covers
sha256sum --ignore-missing -c checksums.txt   # macOS: shasum -a 256 --ignore-missing -c

从源代码运行

git clone https://github.com/FraiseHQ/fraise
cd fraise
make dev

你的第一条记忆

curl -X POST localhost:9876/api/v1/q \
  -H 'content-type: application/json' \
  -d "{\"query\": \"remember 'the parrot is turquoise' topic:color\"}"

curl -X POST localhost:9876/api/v1/q \
  -H 'content-type: application/json' \
  -d '{"query":"recall parrot"}'

{
  "results": {
    "count": 1,
    "hits": [
      { "value": "the parrot is turquoise", "timestamp": "...", "score": 0.2867 }
    ]
  }
}

在 Agent 中使用

MCP

fraise mcp 是一个 stdio MCP 服务——它是通向运行中守护进程的轻量桥接层，让任何 MCP 客户端都可以记忆和回忆。它提供两个工具：recall 和 remember；如果守护进程使用默认地址，则无需指定任何标志。

先启动守护进程（使用 brew services start fraise，或在 Linux 上使用 systemctl --user start fraise），然后在你使用的编码 Agent 中注册该桥接层。

Claude Code

claude mcp add fraise -- fraise mcp

这会为当前项目注册该服务；添加 --scope user，即可在所有项目中使用。

Codex

codex mcp add fraise -- fraise mcp

或者直接写入 ~/.codex/config.toml：

[mcp_servers.fraise]
command = "fraise"
args = ["mcp"]

OpenCode

将其添加到项目根目录下的 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fraise": {
      "type": "local",
      "command": ["fraise", "mcp"]
    }
  }
}

其他客户端

{
  "mcpServers": {
    "fraise": { "command": "fraise", "args": ["mcp"] }
  }
}

该桥接会通过 MCP 自我描述：每个工具都会附带描述，以及其参数和结果的完整 JSON schema——包括 FQL 结构、完整示例和分数的含义——因此客户端无需额外说明，就能知道 recall 和 remember 的作用及调用方式。工具描述无法承载的是策略：主动调用记忆的习惯，以及判断哪些内容值得保留的能力。这应写在 Agent 已经会读取的文件中——Claude Code 使用 CLAUDE.md，Codex 和 OpenCode 使用 AGENTS.md——只需养成两个习惯：回答任何依赖先前决策或偏好的问题前，先进行回忆；只记住以后仍然有用的事实，每次调用记录一条独立完整的事实，并附上便于查找的主题和实体。

SDK

Python（sdk/python）——目前唯一提供的 SDK：

pip install --pre fraise-sdk

from fraise_sdk import FraiseClient

with FraiseClient("http://localhost:9876") as fraise:
    fraise.remember("the parrot is turquoise", topics=["color"])
    for hit in fraise.recall("parrot", top=5):
        print(hit.value, hit.score)

Python SDK 依赖较少，提供 embedder 时支持向量搜索。有关 embeddings 和完整 API，请参阅其 README。

TypeScript——尚不可用（#179）。在此功能推出前，TypeScript 调用方可使用 fraise mcp，或直接调用 HTTP 端点；它通过一个路由提供两个动词，因此客户端只需用 fetch 编写一个简短封装。请参阅 HTTP API。

Claude Agent SDK

Python SDK 为 Claude Agent SDK 提供记忆工具，并将其作为进程内 MCP 服务暴露，因此由 Agent 决定要存储和回忆哪些内容：

from claude_agent_sdk import ClaudeAgentOptions
from fraise_sdk import FraiseClient
from fraise_sdk.integrations.claude_agents import memory_server, allowed_tools

fraise = FraiseClient("http://localhost:9876")
options = ClaudeAgentOptions(
    system_prompt="Remember durable facts the user shares, and recall them when relevant.",
    mcp_servers={"fraise_memory": memory_server(fraise)},
    allowed_tools=allowed_tools(),
)

一个可通过 Docker 运行的完整 Agent 示例位于 examples/claude-agent-sdk。

OpenAI Agents SDK

memory_tools(client) 会返回绑定好的 recall 和 remember 工具：

from agents import Agent, Runner
from fraise_sdk import FraiseClient
from fraise_sdk.integrations.openai_agents import memory_tools

fraise = FraiseClient("http://localhost:9876")
agent = Agent(
    name="Assistant",
    instructions="Remember durable facts the user shares, and recall them when relevant.",
    tools=memory_tools(fraise),
)

result = Runner.run_sync(agent, "My favourite colour is orange.")
print(result.final_output)

一个可通过 Docker 运行的完整 Agent 示例位于 examples/openai-agents。

参考资料

• 路线图
• 文档
• 架构
• 查询语言语法
• 发布流程
• 问题

参与贡献

欢迎贡献——有关构建、测试和提交更改的方法，请参阅 CONTRIBUTING.md。

行为准则

本项目遵循 Contributor Covenant。

社区

对 Fraise 有疑问、想法，或正在使用 Fraise 构建项目？欢迎加入 Discord。Bug 和功能请求请提交到 issues，以免遗漏。

许可证

MIT——详见 LICENSE。