mcpField
P
Perenna

Perenna

本地服务
github.com/scarletkc记忆与知识617 周前更新
代码仓库

关于 Perenna

Perenna 是一个轻量级的 MCP 服务，为 AI Agent 提供基于 Git 的持久记忆。它面向希望在 Claude Code、Codex、ChatGPT、Cursor 等客户端之间共享记忆的用户，记忆以可读的 Markdown 文件保存。

主要功能

  1. 01独立的读取、写入、删除记忆工具
  2. 02支持本地 stdio 与远程 HTTP 连接
  3. 03记忆以 Markdown 存储于独立 Git 仓库
  4. 04本地 Vexor 检索索引，可从 Git 重建
  5. 05多个本地进程之间的跨进程锁定

适用场景

  1. 01在多个 AI 客户端之间共享长期记忆
  2. 02将记忆纳入 Git 版本管理与备份
  3. 03通过可自托管的服务连接 ChatGPT 与本地 Agent

MCP 相关

Perenna 作为 MCP 服务运行，向客户端暴露记忆的读取、写入和删除工具。它支持本地 stdio、仅限回环地址的 Streamable HTTP 以及 OAuth 保护的远程 HTTP 连接。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "scarletkc-perenna": {
      "command": "uvx",
      "args": [
        "perenna"
      ],
      "env": {
        "PERENNA_GIT_REMOTE": "<PERENNA_GIT_REMOTE>",
        "VEXOR_API_KEY": "<VEXOR_API_KEY>",
        "VEXOR_REMOTE_RERANK_API_KEY": "<VEXOR_REMOTE_RERANK_API_KEY>",
        "VEXOR_CONFIG_JSON": "<VEXOR_CONFIG_JSON>"
      }
    }
  }
}
启动命令uvx perenna
需要配置的环境变量
PERENNA_GIT_REMOTEGit remote name used for optional synchronization (for example, origin); leave unset for local-only operation
VEXOR_API_KEY密钥Embedding provider API key (optional; overrides a stored key; providers can also be configured via `vexor init`)
VEXOR_REMOTE_RERANK_API_KEY密钥Remote reranker API key (optional; overrides a stored key; only needed when rerank is set to remote)
VEXOR_CONFIG_JSONNon-secret Vexor config as a JSON object, e.g. {"provider": "gemini", "rerank": "bm25"} (optional; merged over ~/.vexor/config.json; credential fields are rejected, use the dedicated variables)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypiperenna0.4.1

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Perenna 标志

Perenna

Python PyPI CI Codecov CodeRabbit Pull Request Reviews License Ask DeepWiki perenna MCP server

轻量级、由 Git 支持的 AI Agent 持久记忆。Claude Code、Codex、 ChatGPT、Cursor 和其他 MCP 客户端可以共享持久记忆，而无需 共享供应商账号或对话历史。

  • 用于读取、写入和删除记忆的独立 MCP 工具
  • 本地 stdio、仅限环回访问的 Streamable HTTP，以及受 OAuth 保护的远程 HTTP
  • 存储在独立 Git 仓库中的易读 Markdown
  • 本地 Vexor 检索索引，始终可以从 Git 重建
  • 支持多个本地 Agent 进程的跨进程锁定

为什么选择 Perenna？

你的记忆应该跟随你，而不是你正在使用的 Agent。

Claude Code、Codex、Cursor 和 ChatGPT 将记忆保存在彼此隔离的空间中。切换 Agent，记忆就会消失。更换设备，本地记忆也会留在原处。

Perenna 为它们提供一个共享的、由 Git 支持的记忆库。本地 Agent 和 ChatGPT 可以连接到同一个可自托管的 Perenna 服务，而每条持久记忆 都以普通 Markdown 的形式保存，你可以自行检查、编辑、版本管理和备份。

Perenna 专注于持久记忆：无需账号、专有记忆云，也不会自动提取对话内容。

快速入门

与你的 AI Agent 一起安装

将以下内容粘贴到 Claude Code、Codex、ChatGPT Desktop、Cursor 或其他具备终端和本地 MCP 配置访问权限的编码 Agent 中：

Open the following URL, read the complete instructions, and follow them to
install and connect Perenna:
https://raw.githubusercontent.com/scarletkc/Perenna/main/docs/guides/agent-installation.md
安装已发布的版本

Perenna 需要 Python 3.12+、Git 和 uv。

安装 Perenna
uv tool install perenna
配置检索

Perenna 需要可正常运行的 Vexor 嵌入提供程序。要交互式选择和配置提供程序，请运行：

uvx vexor init

Perenna 会自动复用 ~/.vexor/config.json。使用进程级配置时，请确保 MCP 服务收到 VEXOR_CONFIG_JSON，以及 VEXOR_API_KEY 或所选提供程序从其宿主环境中读取的密钥。 远程提供程序会接收记忆文本和搜索查询。

如果选择本地嵌入，还需安装 Perenna 的本地 extra：

uv tool install "perenna[local]"

Vexor 提供程序配置 介绍了远程和本地设置。从启动 MCP 客户端的环境中运行以下命令，验证所选提供程序：

uvx vexor doctor
连接客户端

对于独立部署，请配置 MCP 客户端以启动：

perenna mcp

请参阅 客户端配置指南， 了解准确的客户端命令或配置文件。

Codex 和 Claude Code 也可以安装可选的记忆行为 Skill：

perenna skill install --agent codex
# or
perenna skill install --agent claude-code

如果要让两个客户端都获取该 Skill，请在一条命令中重复使用 --agent。 配置参考 介绍了用户和项目级别的范围、目标位置以及替换保护措施。

Codex 和 Claude Code 也可以从 Perenna 的仓库 Marketplace 安装组合式 Skill 和 MCP 连接。 请遵循 插件配置指南， 并为每个客户端选择一种配置方式。

除非配置了其他主目录，否则 Perenna 会在 ~/.perenna/ 下创建本地数据。

添加可选的 Git 同步

若要通过私有 Git 仓库导入、发布或快进兼容历史，请运行：

perenna sync setup <repository-url>

配置成功后，选定的远程地址会保存到 Perenna 主目录。使用 perenna sync disable 可恢复为仅使用已保存本地数据的模式，而不会移除 Git 远程地址。

配置参考 说明了远程地址选择、凭据、冲突处理和恢复详情。

从源代码安装
git clone https://github.com/scarletkc/Perenna.git
cd Perenna
uv tool install .

源代码贡献者应使用 开发指南 中锁定的环境。

文档

请从 文档索引 开始，然后根据任务选择相应的内容：

许可证

MIT

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。