Pensyve

Pensyve

Pensyve 是一个用于持久化 AI Agent 记忆的开源运行时。它存储事实、 对话、观察结果和行动结果，让 Agent 能在后续会话中检索这些内容。 你可以通过 Python、模型上下文协议（ MCP）服务、命令行工具或 REST API 使用它。

Rust 引擎使用 SQLite 进行本地存储，并在本地运行嵌入模型， 以便按含义进行搜索。TypeScript 和 Go 客户端连接到你自行运行的网关。 本地使用无需 Pensyve 账户或 API 密钥。 你的应用或客户端集成会调用 Pensyve 来保存和检索 记忆。

选择一种配置方式

用途	从这里开始
为 Python Agent 添加持久化记忆	Python 快速入门
让 Claude Code、Cursor 或 Codex 使用记忆工具	MCP 服务和客户端配置指南
通过 TypeScript、Go 或 REST 共享记忆存储	HTTP 网关
使用 LangChain 或 LangGraph 适配器	Python 集成或TypeScript 集成

项目状态

Pensyve Cloud 已于 2026 年 10 月 1 日关闭。开源项目将继续在 此仓库中以 Apache 2.0 许可证维护，引擎、SDK、 集成和文档均可在此获取。

Pensyve 目前处于维护模式。版本更新仅包含安全修复和依赖项 更新，暂无新功能计划。有关贡献和支持的预期，请参阅维护政策。 如果你已保存 Cloud 导出文件，请参阅自托管指南， 了解如何将其用于自己的网关。

你可以做什么

• 存储有关用户、项目或其他命名实体的事实，并将对话记录为片段。
• 使用文本匹配、嵌入以及实体之间的关系搜索记忆。
• 记录观察结果和行动结果，并使用整合来提升重复事实的优先级并更新记忆保留策略。
• 将数据保存在本地 SQLite 存储中，或使用 SQLite 或 PostgreSQL 运行 HTTP 网关。

首次加载嵌入模型时，可能会下载模型，除非模型已缓存。 如需在无网络访问的情况下运行，必须先准备好模型文件。 请参阅模型配置和部署指南。

Agent 记忆的工作原理

Pensyve 在大模型之外存储记忆。你的应用会保存 事实或对话、搜索相关记录，并将结果添加到后续的提示词中。 重复使用相同的存储路径和命名空间，可以让 Agent 跨进程和会话检索信息。保存记忆 不会训练大模型，也不会改变其权重。

存储中有四类记录：事实（语义记忆）、对话 （情景记忆）、行动结果（程序性记忆）和观察结果。 由你的集成决定记录什么以及何时检索。记录 对话不会自动将其转化为成功的程序。请参阅存储和检索的工作原理以及 使用示例，了解 API 及其限制。

Python 快速开始

需要 Python 3.10 或更高版本。

pip install pensyve

创建本地存储，保存一条事实并检索：

import pensyve

p = pensyve.Pensyve(path="./memories", namespace="my-agent")
user = p.entity("user", kind="user")

p.remember(
    entity=user,
    fact="Prefers dark mode and vim keybindings",
    confidence=0.95,
)

for memory in p.recall("editor preferences", entity=user):
    print(memory.content)

在后续进程中使用相同的路径和命名空间来检索已保存的记忆。Python SDK 会在你的进程中运行引擎，无需 HTTP 网关。

你也可以使用相同的 p 和 user 记录对话：

with p.episode(user) as episode:
    episode.message("user", "Use dark mode in my editor")
    episode.message("agent", "I updated the editor settings")
    episode.outcome("success")

groups = p.recall_grouped("editor settings", limit=10)
for group in groups:
    for memory in group.memories:
        print(memory.content)

recall_grouped() 会按来源会话对结果分组，以便在 Agent 的提示词中使用。更多示例请参阅 Python SDK 指南和实用教程。

MCP 服务

Pensyve 的本地 MCP 记忆服务让 Claude Code、Codex 和 Cursor 等客户端能够跨会话存储和检索记忆。在本仓库的检出目录中，使用 Rust 1.94 或更高版本安装该服务：

git clone https://github.com/major7apps/pensyve.git
cd pensyve
cargo install --path pensyve-mcp --locked

确保 Cargo 的二进制文件目录位于客户端的 PATH 中，然后在其 MCP 配置中添加一个 stdio 服务条目：

{
  "mcpServers": {
    "pensyve": {
      "command": "pensyve-mcp",
      "args": ["--stdio"],
      "env": {
        "PENSYVE_NAMESPACE": "my-project"
      }
    }
  }
}

该服务提供 pensyve_remember、pensyve_recall、pensyve_observe 和 pensyve_inspect 等工具。它会在本地存储数据，无需 API 密钥。配置文件的位置取决于你的客户端。请参阅 MCP 设置指南和集成指南。

HTTP 网关

运行网关即可通过 REST 或 MCP HTTP 访问 Pensyve，TypeScript 和 Go SDK 也可使用。从仓库根目录启动本地实例：

HOST=127.0.0.1 PENSYVE_API_KEYS=psy_local_example \
  cargo run --release -p pensyve-mcp-gateway

在另一个终端中保存并检索一条事实：

curl http://localhost:3000/v1/remember \
  -H "Authorization: Bearer psy_local_example" \
  -H "Content-Type: application/json" \
  -d '{"entity":"user","fact":"Prefers Python","confidence":0.95}'

curl http://localhost:3000/v1/recall \
  -H "Authorization: Bearer psy_local_example" \
  -H "Content-Type: application/json" \
  -d '{"query":"programming language","entity":"user"}'

MCP HTTP 端点为 http://localhost:3000/mcp。在客户端的 Authorization: Bearer 标头中使用相同的 API 密钥。

示例密钥仅用于本地测试。部署时，请选择带有所需 psy_ 前缀的自定义密钥，并配置 HTTPS 和允许的主机。请参阅自托管指南、网关配置和安全文档。

SDK 和集成

TypeScript 和 Go SDK 需要运行中的网关。配置网关 URL；如果启用了身份验证，还需配置该网关提供的 API 密钥。

接口	安装或指南
Python	pip install pensyve，SDK 指南
TypeScript	npm install @pensyve/sdk，SDK 指南
Go	go get github.com/major7apps/pensyve/pensyve-go/v5@latest，SDK 指南
Claude Code	插件设置
Cursor	MCP 设置和规则
Codex	插件设置
LangChain 和 LangGraph	Python 适配器，TypeScript 适配器
其他客户端和框架	集成索引

命令行工具

在仓库根目录安装 CLI 并查看其命令：

cargo install --path pensyve-cli --locked
pensyve --help
pensyve status
pensyve recall "editor preferences" --entity user

二进制文件名为 pensyve。默认输出为 JSON，使用 --format text 可选择文本输出。CLI 使用自己的默认本地存储位置；不会自动打开 Python 示例中的 ./memories 目录。有关存储和命名空间选项，请参阅 CLI 源代码和命令定义。

文档

指南	内容
文档索引	选择一种配置方式，查找 API 指南，并了解历史计划
快速入门	按客户端或 SDK 配置
自托管	网关部署、模型文件、备份和保存的 Cloud 导出内容
使用示例	回忆、事实、事件、观察及其他 API 示例
架构	存储、检索和组件边界
安全	身份验证、命名空间隔离和执行限制
可靠性	测试和运行时保证
更新日志	发布历史和重大变更

开发与贡献

请先阅读 CONTRIBUTING.md，了解先决条件和配置方法。 在仓库根目录运行：

uv sync --extra dev
make build
make check

make build 会编译 Rust 并构建 Python 扩展。make check 会运行 Rust 和 Python 的 lint 及测试命令。TypeScript 和 Go 有单独的检查， 详见贡献指南。

问题和拉取请求遵循维护政策。 请通过私密漏洞报告报告安全问题。

许可证

Pensyve 基于 Apache 2.0 许可协议授权。