Memora

社区

为你的 AI 智能体提供持久的集体记忆

分类: 其他第 71 / 230
Stars: ★ 742 非常热门
传输方式: stdio（本地进程） · SSE · Streamable HTTP
运行环境: Python
凭据: 可选 API Key
许可证: MIT
最近提交: 31 天前
工具数: 31

60FMRS · C

Memora 是一个社区维护（MIT 许可，非厂商官方）的 MCP 记忆层，把 AI 智能体的跨会话记忆做成可检索、可追溯、可视化的图谱数据。它的差异化在于 absorb 的 LLM 分类写入与取代血缘机制——更新不是覆盖而是新增版本并沿链检索——再加上 memory_digest 的主题聚合检索、结构化文档片段存储和内置图谱 UI。代价是配置面较大：嵌入与 LLM 是两个独立可拆分的供应商配置，存在部分拆分被拒绝、端点错误导致静默降级等陷阱；容器化部署还需常驻代理与 LaunchAgent。适合愿意自行配置密钥与端点、并对跨会话记忆有实际需求的团队；不适合追求零配置或需要官方支持的场景。

最强项 · 文档质量 14/20 最弱项 · 安全与权限 11/20

可靠性

12/20

安全与权限

11/20

维护活跃度

11/20

文档质量

14/20

安装易用性

12/20

查看各项评分依据

可靠性 12/20: README 描述了清晰的主流程（pip 安装 memora-mcp、memora-server 启动、stdio/HTTP 传输、启动时工具配置文件校验、健康检查端点），并坦诚披露了若干失败模式（OpenRouter 无 embedding 端点导致 404 后静默降级为 TF-IDF、D1 单次响应竞速 30s 上限、容器 IP 每次启动变化导致静默挂起、LaunchAgent 只监管代理而非容器）。这些坦诚的失败说明是有价值的可诊断性证据。但全部是文本声明：仓库中未提供任何 CI 工作流或已提交的测试文件内容作为可验证的执行证据，也没有服务器清单缓存。因此按静态校准上限只能给 12 分（关键路径看似合理，但测试/边界证据稀薄），不因流行度加分。
安全与权限 11/20: README 展示了较严谨的凭据与权限设计：凭据不写入镜像/实例文件/客户端 HTTP 配置，运行时从独立凭据文件注入并建议 chmod 600；MEMORA_HEALTH_TOKEN 保护详细健康信息、非回环对端只得到聚合状态；MEMORA_TOOL_PROFILE 未知值拒绝启动（fail closed），避免把 memory_rebuild_embeddings、memory_delete_batch 暴露给 worker；MEMORA_DATABASES 名称校验、未知库返回 404 且不泄露其他库名；会话粘性绑定防止半途切换数据库。扣分点：默认示例直接使用本地 SQLite 并在客户端 JSON 中放置真实占位密钥形式（虽为 REPLACE 占位，但 README 引导用户把真实 OPENAI_API_KEY/CLOUDFLARE_API_TOKEN 放入 .mcp.json 与 ~/.config/memora/credentials.mcp.json）；memory_delete/批量删除/merge 等破坏性操作在文档中未见明确二次确认要求；HTTP 传输默认可绑定 127.0.0.1 但 --host 可被覆盖，且 FastMCP 的 custom_route() 健康端点被自述为在配置 MCP 认证时仍不鉴权。未触及红线，故不落 0-4 区间。
维护活跃度 11/20: 可见信号为正：MIT 许可、719 stars、仅 2 个开放 issue、有版本徽章与 releases 链接、被 Awesome Claude Code 提及，README 记录了具体 issue 编号（如 #973）与修复后果，显示持续维护和版本化行为变更。但静态材料中没有实际的提交历史、发布日期、CI 状态、依赖更新记录或安全响应通道说明；所有权归属仅有仓库组织名 agentic-box，无治理/维护者信息；依赖被硬性 pin 在 mcp>=1.27,<1.28，升级需重跑测试，属于明显的版本化耦合风险。这些治理与证据缺口使其维持在中段，而非高分。
文档质量 14/20: 文档是此项目的强项：分层结构（Features/Install/Configuration/环境变量表/工具配置/多库路由/容器部署/嵌入/图谱/聊天/去重/文档存储/洞察/链接/Neovim），环境变量逐项列出默认值、上限、非法值行为与生效范围（如仅 streamable-http），并给出可复制的配置示例、工作示例（OpenRouter LLM + Cloudflare Workers AI 嵌入）、失败陷阱说明（OpenRouter 无嵌入端点导致 TF-IDF 静默降级、指纹变更后必须重建嵌入与交叉引用、容器 IP 变化需代理）。也明确披露了限制（D1 分页是缓解非根治、容器运行时需 macOS 26 + Apple silicon）。扣分原因：部分章节冗长且含大量内部事故叙事，缺少最小可跑的端到端示例与工具参数级别的权威 schema 文档；tool profile 只有数量与成员概述而无逐工具参数说明；没有明确的成本说明；troubleshooting 分散在正文而非独立章节。
安装易用性 12/20: pip 路径非常简短：pip install memora-mcp 后以 memora-server 作为 command 配置即可，属于几步骤可达；容器路径则显著复杂。容器安装要求 Apple container CLI、macOS 26、Apple silicon，需手动创建 ~/.config/memora 三个目录、复制代理脚本、手写凭据 JSON 并 chmod 600、编写实例文件、依次执行 build/up/proxy 并自行运行打印出的 launchctl 命令，且 README 承认全新克隆下没有任何目录或文件被自动创建、LaunchAgent 只监管代理不监管容器（主机重启后监听端口可能恢复而上游仍停止）。这类手动、平台受限、易碎的安装流程按校准要求不能超过 15；缺乏 CI/测试的可执行证据也限制上限，故给 12。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络连接数据库

适合谁

使用 Claude Code、Codex CLI 等 MCP 客户端并需要跨会话记忆的开发团队
希望自托管 SQLite 或使用 Cloudflare D1/R2 做云同步的用户
需要取代血缘（supersession lineage）与去重、而不只是追加文本的长期记忆场景
愿意自行配置嵌入与 LLM 供应商（OpenAI、OpenRouter、Cloudflare Workers AI 等）的高级用户

不适合谁

只想零配置开箱即用的用户——嵌入与 LLM 需要自行准备密钥与端点
不需要持久记忆、单次问答即可完成任务的场景
不愿承担运行容器或 LaunchAgent 代理这类常驻服务运维成本的环境
期望官方厂商支持或 SLA 的用户——该项目由社区维护

所需权限

本地文件读写：创建并读写 SQLite 数据库文件（默认 ~/.local/share/memora/memories.db）及缓存目录
网络访问：调用配置的嵌入端点与 LLM 端点（OpenAI、OpenRouter、Cloudflare Workers AI 等）
云存储凭证：使用 S3/R2 同步时需 AWS_PROFILE、AWS_ENDPOINT_URL 等凭证；使用 D1 时需 CLOUDFLARE_API_TOKEN
本地端口监听：图谱服务器默认监听 127.0.0.1:8765；HTTP 传输默认 127.0.0.1:8000
容器部署需运行 Apple container CLI，并通过 LaunchAgent 启动本地代理进程

风险与副作用

嵌入端点配置错误时（例如把嵌入指向 OpenRouter），若未设置 MEMORA_EMBEDDING_STRICT=1，Memora 会静默退化为 TF-IDF 关键词匹配，向量质量下降而表面仍显示正常
MEMORA_DATABASES 中写错存储名不会报错：读取正常，但写入会落入另一个项目的存储，需用 memory_stats 核对 database 字段
凭证以环境变量注入进程，配置文件若权限过宽可能被本机其他账户读取（文档建议 chmod 600）
记忆内容会被发送到配置的嵌入与 LLM 服务商，涉及敏感数据时需自行评估
容器运行时每次启动都会重新分配 IP，若不经代理直连会产生静默挂起
LLM 去重与 absorb 可能合并或取代记忆，虽然保留血缘，但错误判断仍会影响检索结果
文档片段受完整性保护，但整篇文档删除会连带删除全部片段

安装接入

准备工作

运行环境：Python

CLOUDFLARE_API_TOKEN 可选密钥访问 Cloudflare D1 的 API 令牌，在 Cloudflare 控制台创建，可用 CF_API_TOKEN 代替。

MEMORA_HEALTH_TOKEN 可选密钥获取详细 /health/db 内容的 Bearer 令牌，自行设定即可。

MEMORA_EMBEDDING_API_KEY 可选密钥嵌入提供商的 API 密钥，须与 MEMORA_EMBEDDING_BASE_URL 成对设置。

OPENAI_API_KEY 可选密钥 LLM（去重/聊天）用的 OpenAI 兼容密钥；嵌入仅在两个 MEMORA_EMBEDDING_* 均未设时回退使用。

其他可选配置项（43 个）

MEMORA_DB_PATH 可选本地 SQLite 数据库路径，默认 ~/.local/share/memora/memories.db。

MEMORA_STORAGE_URI 可选云端存储 URI（d1:// 或 s3://），不设 MEMORA_DATABASES 时使用。

MEMORA_DATABASES 可选 JSON 格式的多数据库注册表 {name: uri}，仅在 streamable-http 下路由生效。

MEMORA_DEFAULT_DB 可选裸 /mcp 路径绑定的注册表数据库名。

MEMORA_CLOUD_ENCRYPT 可选上传 S3/R2 前是否加密本地文件（true/1/yes）。

MEMORA_CLOUD_COMPRESS 可选上传 S3/R2 前是否压缩本地文件。

MEMORA_CACHE_DIR 可选 S3/R2 同步数据库的本地缓存目录。

MEMORA_ALLOW_ANY_TAG 可选设为 1 允许任意标签而不校验白名单。

MEMORA_TAG_FILE 可选包含允许标签数组的 JSON 文件路径。

MEMORA_TAGS 可选逗号分隔的允许标签列表。

MEMORA_HOST 可选 HTTP 传输的绑定地址，默认 127.0.0.1。

MEMORA_PORT 可选 HTTP 传输的绑定端口，默认 8000。

MEMORA_GRAPH_PORT 可选知识图谱可视化服务器端口，默认 8765。

MEMORA_TRANSPORT 可选传输方式：stdio（默认）、sse 或 streamable-http。

MEMORA_TOOL_PROFILE 可选暴露的工具子集：full（43 个）、leader（19 个）或 agent（12 个）。

MEMORA_MAX_SESSIONS 可选并发 MCP 会话硬上限，默认 128，0 禁用。

MEMORA_MAX_INIT_PER_MIN 可选每分钟允许的新会话数，默认 120，0 禁用。

MEMORA_MAX_INIT_BODY_BYTES 可选 initialize 请求体大小上限，默认 65536。

MEMORA_SESSION_IDLE_TIMEOUT 可选空闲会话回收秒数，默认 1800，0 禁用。

MEMORA_HEALTH_TTL 可选就绪快照有效期秒数，默认 10。

MEMORA_HEALTH_TIMEOUT 可选一次健康刷新/单店探测的上限秒数，默认 15。

MEMORA_HEALTH_REFRESH_INTERVAL 可选服务器主动刷新就绪状态的间隔秒数，0 为仅按需轮询。

MEMORA_HEALTH_MAX_STALE 可选缓存结果可报告就绪的最长年龄秒数，默认 60。

MEMORA_STALE_DAYS 可选 TODO/issue 视为过期的天数，insights 默认 14、图 UI 默认 30。

MEMORA_EMBEDDING_MODEL 可选嵌入后端：openai（默认）、sentence-transformers 或 tfidf。

SENTENCE_TRANSFORMERS_MODEL 可选 sentence-transformers 模型名，默认 all-MiniLM-L6-v2。

MEMORA_EMBEDDING_BASE_URL 可选嵌入提供商的 base URL，须与 MEMORA_EMBEDDING_API_KEY 成对设置。

MEMORA_EMBEDDING_STRICT 可选推荐设为 1，嵌入出错时硬失败而非静默回退到 TF-IDF。

OPENAI_BASE_URL 可选 LLM 的 OpenAI 兼容 base URL（如 OpenRouter）。

OPENAI_EMBEDDING_MODEL 可选 openai 嵌入后端的模型 ID，须存在于嵌入主机。

MEMORA_LLM_ENABLED 可选是否启用 LLM 去重比较，默认 true。

MEMORA_LLM_MODEL 可选去重比较模型，默认 gpt-4o-mini。

MEMORA_LLM_TIMEOUT 可选 OpenAI 客户端等待秒数，默认 60。

MEMORA_REWRITE_MODEL 可选图聊天面板 RAG 查询重写模型，未设则用 MEMORA_LLM_MODEL。

MEMORA_VECTOR_SCAN_PAGE_SIZE 可选从 D1 加载嵌入的每页行数，D1 上建议设 100。

CHAT_MODEL 可选本地图聊天面板模型，未设则回退 MEMORA_LLM_MODEL。

MEMORA_CLOUD_GRAPH_ENABLED 可选设为 true/1/yes 时写操作通知托管图谱。

MEMORA_CLOUD_GRAPH_WORKER_URL 可选广播用的 Worker base URL。

MEMORA_CLOUD_GRAPH_DEBOUNCE 可选广播前的写入合并秒数，默认 1.0。

MEMORA_CLOUD_GRAPH_SYNC_SCRIPT 可选启动时捕获的同步脚本路径。

AWS_PROFILE 可选 ~/.aws/credentials 中的 AWS 凭证 profile（用于 R2）。

AWS_ENDPOINT_URL 可选 S3 兼容端点（R2/MinIO）。

R2_PUBLIC_DOMAIN 可选 R2 图片 URL 的公开域名。

方式一（pip，本地 stdio）：1) 执行 pip install memora-mcp（PyPI 包名为 memora-mcp，裸 memora 是无关项目）；如需离线本地嵌入可执行 pip install "memora-mcp[local]"（约 2GB PyTorch）。2) 在项目根的 .mcp.json 中添加 "command": "memora-server"，并按需设置 MEMORA_DB_PATH、MEMORA_ALLOW_ANY_TAG、MEMORA_GRAPH_PORT 等环境变量。3) 重启客户端。
方式二（容器，HTTP 服务）：默认运行时为 Apple 的 container CLI，需 Apple 芯片且 macOS 26。依次执行 container system start；git clone 仓库并 cd 进入；cp instances/example.env instances/myinstance.env 并编辑 PORT 与后端（STORAGE_URI、VOLUME 或 MEMORA_DATABASES）；创建凭证文件 ~/.config/memora/credentials.mcp.json（副本可通过 CRED_SOURCE 指定）并 chmod 600；复制 scripts/memora_proxy.py 到 ~/.local/libexec/memora/；然后执行 ./scripts/memora-instance.sh build myinstance、up myinstance、proxy myinstance，并运行其打印的 launchctl 命令。工作区 URL 为 http://127.0.0.1:<PORT>/mcp（非默认存储需追加 /<name>）。
Codex CLI 则写入 ~/.codex/config.toml 的 [mcp_servers.memora] 段，设置 command 与 env。

.mcp.json

{"mcpServers":{"memora":{"command":"memora-server","args":[],"env":{"MEMORA_DB_PATH":"~/.local/share/memora/memories.db","MEMORA_ALLOW_ANY_TAG":"1","MEMORA_GRAPH_PORT":"8765"}}}}

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "MEMORA_DB_PATH": "~/.local/share/memora/memories.db",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add memora -e 'MEMORA_DB_PATH=~/.local/share/memora/memories.db' -e MEMORA_ALLOW_ANY_TAG=1 -e MEMORA_GRAPH_PORT=8765 -- memora-server

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

安装 memora-mcp 并在客户端配置 memora-server 后，工具列表中应出现 memory_absorb、memory_semantic_search 等工具；调用 memory_stats 若返回 database 字段和记忆数量即证明连接成功。

常见排障

写入似乎成功但检索不到内容：先调用 memory_stats 确认本会话绑定的 database 是否为预期的工作区存储
语义搜索退化为关键词匹配：检查是否设置了 MEMORA_EMBEDDING_STRICT=1，并确认 MEMORA_EMBEDDING_BASE_URL 指向的端点确实提供嵌入接口
更换嵌入模型、端点或向量维度后检索异常：执行 memory_rebuild_embeddings，再执行 memory_rebuild_crossrefs 重建交叉引用
在 D1 上 absorb 超时：把 MEMORA_VECTOR_SCAN_PAGE_SIZE 调小（文档建议 D1 上用 100）
客户端启动后无响应：容器运行时 IP 会变动，需确认通过 scripts/memora_proxy.py 的稳定 127.0.0.1:<PORT> 连接
多存储进程中选择不到存储：/mcp/<name> 中的名称须为注册表条目；未知名称返回 404 unknown database
工具列表比预期少：检查 MEMORA_TOOL_PROFILE，full 暴露全部 43 个工具，leader 为 19 个，agent 为 12 个
HTTP 部署健康检查：GET /health 为存活探针，GET /health/db 汇总各库状态，GET /health/db/{name} 为单库探针

试试这样问

连接成功后，可以直接对 AI 助手这样说：

把这次会话里确定的事实用 memory_absorb 吸收到记忆库，先 dry_run 预览
用 memory_digest 检索一下关于登录流程的已知信息，包括未完成的 TODO 和 issue
帮我语义搜索与'数据库迁移'相关的记忆，并列出相似度最高的几条
调用 memory_stats 看看当前绑定的是哪个数据库、总共有多少条记忆

工具能力 31

memory_absorb 写入

写入事实，由 LLM 分类为重复/更新/矛盾/相关/新增，跳过重复、建立关系并合并相关事实，支持 dry_run 预览

memory_digest 只读

围绕某个主题汇总相关记忆、未完成的 TODO/Issue、关联边与来源 ID

memory_create 写入

创建一条记忆（自动计算嵌入与交叉引用）

memory_update 写入

更新一条记忆

memory_delete 破坏性

删除一条记忆；删除文档片段需 force=True

memory_delete_batch 破坏性

批量删除记忆

memory_get 只读

按 ID 获取单条记忆

memory_list 只读

列出记忆

展开其余 23 个工具

memory_list_compact 只读

以紧凑格式列出记忆

memory_semantic_search 只读

向量语义搜索记忆

memory_hybrid_search 只读

全文与向量的混合检索

memory_related 只读

查找与某条记忆相关的记忆

memory_link 写入

在两段记忆之间建立带类型的边（references、implements、supersedes、extends、contradicts、related_to）

memory_unlink 写入

移除两段记忆之间的链接

memory_boost 写入

提升某条记忆的重要性权重，影响排序

memory_clusters 只读

检测相关记忆形成的簇

memory_stats 只读

返回统计信息，含本会话实际绑定的 database 与 database_source

memory_tags 只读

列出标签

memory_create_todo 写入

创建带状态与优先级的 TODO

memory_create_issue 写入

创建带严重程度与组件的 Issue

memory_create_section 写入

创建章节占位节点（图谱中隐藏）

memory_store_document 写入

将 Markdown 文档解析为带类型的片段树（claim、plan_item、reference、section_chunk、risk）并存储

memory_get_document 只读

按 document_key 取回整篇文档或指定片段类型

memory_delete_document 破坏性

删除文档及其全部片段

memory_find_duplicates 只读

借助交叉引用与可选 LLM 分析查找潜在重复记忆

memory_merge 写入

按 append、prepend 或 replace 策略合并重复记忆；拒绝合并文档片段

memory_detect_supersessions 只读

检测记忆之间的取代关系

memory_rebuild_embeddings 写入

在嵌入模型、端点、模型 ID 或向量维度变化后重建全部嵌入

memory_rebuild_crossrefs 写入

重建交叉引用以更新知识图谱

memory_insights 只读

输出活动摘要、开放条目与陈旧检测、合并建议，以及可选的 LLM 模式分析

memory_export_graph 写入

将记忆导出为静态 HTML 图谱文件以供离线查看

使用场景

让多个智能体会话共享一份持久的项目记忆，避免重复交代上下文

用 memory_absorb 把智能体产出的事实沉淀为带血缘的图谱记忆

用 memory_digest(topic) 一次性取回某主题的相关记忆、未完成 TODO/Issue 与来源 ID

用语义搜索在大量历史记忆中检索相关结论

把研究报告、架构决策、复盘文档存为可逐条检索的片段树

在内置图谱 UI 中查看关系网络、时间线与操作历史

通过 RAG 聊天面板直接对记忆库提问并让模型创建/更新/删除记忆

支持客户端

Claude Code

Codex

Neovim部分支持

依据项目文档列出，未经本站实测。

详细介绍

Memora 是一个面向 AI 智能体的 MCP 记忆层，提供结构化存储、语义检索、图谱关系以及可溯源的跨会话上下文。它使用 SQLite 作为本地存储，并可选同步到云端（S3、R2、Cloudflare D1）。核心能力包括：absorb（由 LLM 对写入事实分类为重复/更新/矛盾/相关/新增，跳过重复并建立关联）、supersession 血缘（更新以取代旧知识而非删除，检索默认沿链取当前版本）、memory_digest(topic) 主题摘要（聚合相关记忆、未完成的 TODO/Issue、关联边与来源 ID）、向量语义搜索（TF-IDF、sentence-transformers、OpenAI 三种后端）、LLM 去重、带类型的记忆链接、结构化文档片段存储、知识图谱可视化与内置实时图谱服务器、RAG 聊天面板、事件通知、统计与洞察、操作历史。一个进程可通过 MEMORA_DATABASES 注册表服务多个工作区，客户端用 /mcp/<name> 路径选择存储。