Memora

在 Claude Code 中完成配置后，服务器会自动运行。手动调用：

# Default (stdio mode for MCP)
memora-server

# With graph visualization server
memora-server --graph-port 8765

# HTTP transport (alternative to stdio)
memora-server --transport streamable-http --host 127.0.0.1 --port 8080

Claude Code

将以下内容添加到项目根目录的 .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"
      }
    }
  }
}

云数据库（Cloudflare D1）——推荐：

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": ["--no-graph"],
      "env": {
        "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>",
        "CLOUDFLARE_API_TOKEN": "<your-api-token>",
        "MEMORA_ALLOW_ANY_TAG": "1"
      }
    }
  }
}

使用 D1 时，请使用 --no-graph 禁用本地可视化服务器。请改用 Cloudflare Pages URL 上托管的图谱（参见云端图谱）。

如果主数据库为 d1://，则除非禁用该数据库的读取复制，否则不会启动（启用时，会话书签无法通过 REST 实现读取后写入）。设置 MEMORA_D1_ALLOW_READ_REPLICATION=1 可继续启动，但会记录警告。

云数据库（S3/R2）——同步模式：

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "AWS_PROFILE": "memora",
        "AWS_ENDPOINT_URL": "https://<account-id>.r2.cloudflarestorage.com",
        "MEMORA_STORAGE_URI": "s3://memories/memories.db",
        "MEMORA_CLOUD_ENCRYPT": "true",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765"
      }
    }
  }
}

Codex CLI

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.memora]
  command = "memora-server"  # or full path: /path/to/bin/memora-server
  args = ["--no-graph"]
  env = {
    AWS_PROFILE = "memora",
    AWS_ENDPOINT_URL = "https://<account-id>.r2.cloudflarestorage.com",
    MEMORA_STORAGE_URI = "s3://memories/memories.db",
    MEMORA_CLOUD_ENCRYPT = "true",
    MEMORA_ALLOW_ANY_TAG = "1",
  }

所有 44 个 MCP 工具都会无条件注册，因此每个 Agent 会话都会注入完整的约 12,700 个 token 的工具架构，即使大多数工具从未被调用。MEMORA_TOOL_PROFILE 可按部署配置工具子集，使受限工具真正不存在——既不会出现在 tools/list 中，也无法调度（call_tool 返回 unknown-tool，而不是隐式执行）。配置会在启动时应用并通过验证；活动配置和公开的工具数量会记录到 stderr。

• 未设置／为空 = full。 现有部署的行为不会改变。
• 未知值会中止启动，并显示列出有效值的消息。绝不会静默回退到 full——拼写错误不能让所有 Worker 重新获得破坏性维护工具（memory_rebuild_embeddings、memory_delete_batch）。必须以失败关闭。
• memory_list 属于 leader，但不属于 agent。此前它的运行时间为 163-174 秒，而 memory_list_compact 在 D1 存储上只需 0.22 秒，因此从两者中移除了它；#973 修复了这一问题（现在约为 1.1 秒）。它仍不属于 agent，因为 Worker 的读取接口有意保持精简，而不是为了速度。
• leader／agent 边界是 memora/tool_profile.py 中的数据（两个 frozenset）。修改只需一行，无需检查 44 个装饰器。
• 清理操作会从 FastMCP 的私有 _tool_manager._tools 字典中删除工具，因此 memora 固定使用 mcp>=1.27,<1.28（已审计的小版本），并在启动时通过底层已注册的 MCP 请求处理器（_mcp_server.request_handlers[ListToolsRequest] / [CallToolRequest]——实际客户端请求使用的调度可调用对象，而不是 FastMCP.list_tools / call_tool Python 辅助函数）运行一次验证。如果已安装的 SDK 将列表查询／调度路由到别处（私有实现发生变化），就会拒绝启动。版本固定是静态保护；验证是运行时保障。提高上限版本前，必须重新运行 tests/test_tool_profile.py。
• 在容器部署中，配置针对每个容器，而角色针对每个Agent。为某个工作区的 leader 和 Worker 提供服务的单个容器需要使用 leader 超集；使用 agent 会从 leader 中移除 create_section／store_document／delete／digest／tags。
• memora-server（即 memora.server.main()）是唯一受支持的配置化服务路径。直接导入 memora.server.mcp 并自行调用 mcp.run() 的嵌入方会完全绕过配置（全局 mcp 仍包含全部 44 个工具）；需要使用配置的嵌入方必须自行调用 apply_tool_profile，或使用 main()。

# Leader deployment — exposes 19 tools
MEMORA_TOOL_PROFILE=leader memora-server

# Agent worker — exposes 12 tools
MEMORA_TOOL_PROFILE=agent memora-server

# Full (default) — all 44 tools, existing behaviour
memora-server

# Typo refuses to start:
# MEMORA_TOOL_PROFILE=agnt memora-server
# Error: unknown MEMORA_TOOL_PROFILE='agnt'; valid values: full, leader, agent

一个 memora 进程即可为所有工作区提供服务。MEMORA_DATABASES 是一个 {name: storage URI} 的 JSON 注册表；客户端通过 /mcp/<name> 访问其存储。选择器是 .mcp.json 中已有的 URL，而不是工具参数——每个工具都添加可选的 db 参数，就有 44 次机会可能忘记设置，而且每次遗漏都会把内容写入别人的存储。

**未设置 MEMORA_DATABASES 时保持旧形式：**使用 MEMORA_STORAGE_URI ／MEMORA_DB_PATH 指定一个后端，并提供一个 /mcp。现有 stdio 部署不会改变。

路由（仅 streamable-http）：

数据库绑定是按 MCP 会话固定的，而非按请求绑定。会话在 /mcp/alpha 上打开后，即使改用 /mcp/beta，仍会解析到 alpha。客户端 无法在对话中途切换数据库。

配置格式错误时会拒绝启动（不会回退到旧数据库）：JSON 无效、内容不是对象、键重复、URI 为空、名称不是单个 URL 路径段，或者注册表中列出多个数据库时未设置 MEMORA_DEFAULT_DB 或其值未知。

示例组合——运行此项，连接到此项。 这是一个可流式传输的 HTTP 监听器，而不是 MCP command 条目（后者会启动一个无法通过 stdio 使用 MCP 的子进程）。凭据存放在服务器进程中。

MEMORA_DATABASES='{"memora":"d1://<account-id>/<memora-db-id>","alpha":"d1://<account-id>/<alpha-db-id>"}' \
MEMORA_DEFAULT_DB=memora \
CLOUDFLARE_API_TOKEN='<token>' \
MEMORA_VECTOR_SCAN_PAGE_SIZE=100 \
memora-server --transport streamable-http --host 127.0.0.1 --port 8000 --no-graph

{
  "mcpServers": {
    "memora": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp/alpha"
    }
  }
}

容器 / 代理变体（此主机常用的启动方式，而非上述命令）：scripts/memora-instance.sh up myinstance 会在容器中启动同一个 HTTP 服务，并将 scripts/memora_proxy.py 放在 127.0.0.1:<PORT> （memora 实例使用 8910）。此时工作区 URL 为 http://127.0.0.1:8910/mcp/alpha。请参阅容器部署。

注册表可以混用 d1://、s3:// 和本地路径；parse_backend_uri 会根据方案进行分派。

memory_stats 会报告绑定的数据库。 它会返回 database（此会话实际解析到的名称）和 database_source（path、 registry_default 或 unconfigured）。.mcp.json 中名称有效但错误时，其他方式无法察觉：所有工具都能正常工作，读取成功，写入却会悄然落入其他项目的存储区。请调用 memory_stats，并检查 database 是否与目标工作区一致。

多数据库进程的健康状态：GET /health 用于存活检测（不进行数据库 I/O ——这是监督程序唯一可以据此重启进程的信号）。GET /health/db 用作告警接口（始终返回 HTTP 200；status 为 ok、degraded、unknown——尚无快照、刷新超时或证据已超过最大陈旧时间——或者在注册表本身不可用时为 error）。GET /health/db/{name} 是针对特定工作区的探测接口（返回 200 或 503）。因为一个存储区状态降级就撤下整个进程，会连带影响健康的存储区。

未设置 MEMORA_DATABASES 时，进程在其生命周期内仍只绑定一个数据库（MEMORA_STORAGE_URI / MEMORA_DB_PATH）。这就是原有的一个存储区、一个容器、一个端口的模式。

设置 MEMORA_DATABASES 后，一个容器可服务所有工作区，客户端通过 URL 路径（/mcp/<name>）选择存储区。请参阅 多数据库路由。scripts/memora-instance.sh 要求每个实例文件设置 STORAGE_URI、VOLUME 或 MEMORA_DATABASES 之一（load() 至少要求其中一项）。如果设置了多项，cmd_up 会依次使用 MEMORA_DATABASES、STORAGE_URI，然后是 VOLUME。

Dockerfile 会构建一个不含凭据的镜像；scripts/memora-instance.sh 会从 instances/myinstance.env（或其他具名文件）部署一个实例。该脚本的运行时 CLI 为 $MEMORA_CONTAINER_BIN（默认为 container——Apple 的 CLI）。脚本执行的每项容器操作都会遵循此覆盖值（build、up、status、 logs、down）。生成的 memora_proxy.py 进程会将 container list 写死，这也是代理存在的原因：该运行时会在每次启动时重新分配容器的 IP。

./scripts/memora-instance.sh build   myinstance   # build the image
./scripts/memora-instance.sh up      myinstance   # run the container
./scripts/memora-instance.sh proxy   myinstance   # render a LaunchAgent + print install commands
./scripts/memora-instance.sh status                # every instance at a glance

然后将工作区指向它——完整的客户端配置，不包含任何密钥。 注册表实例需要在路径中指定存储区（/mcp/<name>）；单独的 /mcp 则使用注册表默认值：

{"mcpServers": {"memora": {"type": "http", "url": "http://127.0.0.1:8910/mcp/alpha"}}}

凭据不会进入镜像、实例文件或工作区的 HTTP 配置。 凭据会在运行时从单独的凭据配置中读取（$CRED_SOURCE——该文件本身是一个 .mcp.json，仅包含 mcpServers.memora.env 块），并通过 -e 注入。如果实例文件未设置 CRED_SOURCE，脚本会使用 ~/.config/memora/credentials.mcp.json（若该文件不存在，up 会拒绝运行；没有其他回退方式）。请传入该文件定义的所有变量，而不是只挑几个：如果容器只启动并传入嵌入相关的密钥，memory_absorb 的 LLM 整合功能会悄无声息地失效，而不会明确报错。

代理存在的原因——决定不需要它之前，请先阅读。 默认运行时（Apple 的 container）会在容器每次启动时（不只是重新创建时）重新分配 IP。MCP 客户端只会在启动时读取一次配置，因此地址变更不会报错，而是导致永久的无声挂起。scripts/memora_proxy.py 会在不断变化的地址前提供稳定的 127.0.0.1:<PORT>，并在每次连接时重新解析地址。

它可以区分以下两种故障模式；我们曾付出一次服务中断的代价才弄清楚这一点：

• 查询成功运行，但列表中没有该容器 → 容器确实已不存在。拒绝运行。
• 查询无法运行（主机内存压力下超时）→ 没有新的信息。继续使用上次已知的正常地址，但最长不超过 MEMORA_PROXY_STALE_GRACE（300s）。将这两种情况混为一谈，曾导致所有工作区离线，而容器仍在原地址正常响应。

请按实例设置 MEMORA_TOOL_PROFILE（参见 工具配置）。请注意，配置是针对容器的，而角色是针对Agent的：如果一个容器同时服务于某个工作区的负责人和工作节点，就需要包含负责人的完整工具集。

部署时使用的脚本变量（不是 memora-server 环境变量——它不会传入容器内的进程）：

instances/README.md 介绍配置字段，launchd/README.md 介绍受监管的代理。REVERT.md 介绍如何将工作区恢复为直接使用 stdio 服务端。

Memora 支持三种嵌入后端：

嵌入和 LLM 分开配置。

仅设置一个 MEMORA_EMBEDDING_* 变量的部分分离配置会被拒绝，以免将某个提供商的密钥发送到其他主机。

注意：OpenRouter 没有嵌入端点。 OpenRouter 的目录仅包含聊天和多模态功能（没有嵌入模型）。不要通过 OPENAI_BASE_URL（或 MEMORA 基础 URL）将嵌入路径指向 OpenRouter。这样会导致所有嵌入调用都返回 404；如果未设置 MEMORA_EMBEDDING_STRICT=1，Memora 会回退到 TF-IDF 并继续响应，因此存储中会填满关键词集合，但系统看起来仍正常。OpenRouter 仍然可以只用于 LLM。

示例（通过 OpenRouter 使用 LLM，通过 Cloudflare Workers AI 生成嵌入）：

@cf/baai/bge-m3 的维度为 1024。Token 需要拥有 Workers AI 权限。端点格式：

https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1

{
  "env": {
    "MEMORA_EMBEDDING_MODEL": "openai",
    "OPENAI_API_KEY": "<openrouter-key>",
    "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
    "MEMORA_LLM_MODEL": "deepseek/deepseek-chat",
    "MEMORA_EMBEDDING_API_KEY": "<cloudflare-api-token-with-workers-ai>",
    "MEMORA_EMBEDDING_BASE_URL": "https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1",
    "OPENAI_EMBEDDING_MODEL": "@cf/baai/bge-m3",
    "MEMORA_EMBEDDING_STRICT": "1"
  }
}

此修复的作用（不夸大）：嵌入和 LLM 可以使用不同的提供商；不完整的拆分会被拒绝；严格模式会将静默降级转为明确命名的硬性失败。

自动： 执行 memory_create、memory_update 或 memory_create_batch 时，会自动计算嵌入和交叉引用。

需要手动重建的情况：存储指纹发生变化时——不只是 MEMORA_EMBEDDING_MODEL，还包括：

• 嵌入端点（MEMORA_EMBEDDING_BASE_URL / 主机）
• 实际模型 ID（OPENAI_EMBEDDING_MODEL，例如切换到 @cf/baai/bge-m3）
• 向量类型或维度（词键 TF-IDF 袋与密集型 1024 维向量；或 384 维与 1024 维）
• 混合存储（部分行是密集型，部分是稀疏型）——余弦相似度只比较相同的键，因此混合类型会导致旧行的召回率为 0.0

指纹格式：backend|model|repr（例如 openai|@cf/baai/bge-m3|dense:1024）。旧版元数据值 openai 会被视为不匹配。

# After changing embedding model/endpoint, rebuild all embeddings
memory_rebuild_embeddings

# Then rebuild cross-references to update the knowledge graph
memory_rebuild_crossrefs

内置 HTTP 服务会随 MCP 服务自动启动，提供交互式知识图谱可视化。

详情面板

时间线面板

本地访问：

http://localhost:8765/graph

通过 SSH 远程访问：

ssh -L 8765:localhost:8765 user@remote
# Then open http://localhost:8765/graph in your browser

配置：

{
  "env": {
    "MEMORA_GRAPH_PORT": "8765"
  }
}

要禁用此功能：在 MCP 配置的 args 中添加 "--no-graph"。

图谱 UI 功能

• 详情面板 - 查看记忆内容、元数据、标签和相关记忆
• 时间线面板 - 按时间顺序浏览记忆，点击即可在图谱中高亮显示
• 历史记录面板 - 所有操作的日志，连续条目会分组显示，记忆引用可点击（已删除的记忆以删除线显示）
• 聊天面板 - 使用 RAG 驱动的 LLM 聊天功能提问记忆，支持流式响应和可点击的 [Memory #ID] 引用
• 时间滑块 - 按日期范围筛选记忆，拖动以浏览历史
• 实时更新 - 记忆发生变化时，图谱、时间线和历史记录会通过 SSE 更新
• 筛选器 - 标签/章节下拉菜单、缩放控件
• Mermaid 渲染 - 将代码块渲染为图表

节点颜色

• 🟣 标签 - 按标签使用不同深浅的紫色
• 🔴 问题 - 红色（未解决）、橙色（处理中）、绿色（已解决）、灰色（不予修复）
• 🔵 待办事项 - 蓝色（未开始）、橙色（处理中）、绿色（已完成）、红色（已阻塞）

节点大小反映连接数量。

使用 Cloudflare D1 作为数据库时，图谱可视化托管在 Cloudflare Pages 上，无需本地服务。

优势：

• 随时随地访问（无需 SSH 隧道）
• 通过 WebSocket 实时更新
• 通过 ?db= 参数支持多个数据库
• 使用 Cloudflare Zero Trust 安全访问

设置：

1. 创建 D1 数据库：

   npx wrangler d1 create memora-graph
   npx wrangler d1 execute memora-graph --file=memora-graph/schema.sql
   

2. 部署 Pages：

   cd memora-graph
   npm run deploy
   

   npm run deploy 会先运行 scripts/d1_write_guard.py --scope all，发现任何问题时都会拒绝部署。不要直接运行 wrangler pages deploy：这会绕过防护检查（docs/local-primary-implementation.md §0 P6）。

3. 在 Cloudflare Dashboard 中配置绑定：

   • Pages → memora-graph → Settings → Bindings
   • 添加 D1：DB_MEMORA → 你的数据库
   • 添加 R2：R2_MEMORA → 你的存储桶（用于图片）

4. 使用 D1 URI 配置 MCP：

   {
     "env": {
       "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>",
       "CLOUDFLARE_API_TOKEN": "<your-token>"
     }
   }
   

访问地址： https://memora-graph.pages.dev

使用 Zero Trust 保护：

1. Cloudflare Dashboard → Zero Trust → Access → Applications
2. 为 memora-graph.pages.dev 添加应用程序
3. 创建允许指定电子邮件地址的策略
4. Pages → Settings → 启用 Access Policy

有关详细设置和多数据库配置，请参阅 memora-graph/。

直接在图形界面中询问知识库相关问题。聊天面板使用 RAG（检索增强生成）搜索相关记忆，并以流式方式返回 LLM 响应，同时支持工具调用。

• 通过右下角的浮动聊天图标切换
• 语义搜索会将最相关的记忆作为上下文
• 流式响应包含可点击的 [Memory #ID] 引用，点击后会聚焦到图中的对应节点
• 工具调用——LLM 可以直接在聊天中创建、更新和删除记忆（例如，“将此保存为记忆”、“删除记忆 #42”、“更新记忆 #10，内容为……”）
• 本地服务和 Cloudflare Pages 部署均可使用

配置聊天模型：

需要兼容 OpenAI 的 API（本地服务需要 OPENAI_API_KEY + OPENAI_BASE_URL，Cloudflare 需要 OPENROUTER_API_KEY 密钥）。聊天模型必须支持工具使用（函数调用）。

使用 AI 语义比较查找并合并重复的记忆：

# Find potential duplicates (uses cross-refs + optional LLM analysis)
memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True)

# Merge duplicates (append, prepend, or replace strategies)
memory_merge(source_id=123, target_id=456, merge_strategy="append")

LLM 比较会分析记忆对并返回：

• verdict：“duplicate”、“similar”或“different”
• confidence：0.0-1.0 的置信度分数
• reasoning：简要说明
• suggested_action：“merge”、“keep_both”或“review”

可通过 OPENAI_BASE_URL 搭配任何兼容 OpenAI 的聊天 API（OpenAI、OpenRouter、Azure 等）使用。此 LLM 流程可以使用 OpenRouter；但它不提供嵌入模型——请单独配置嵌入模型（参见“语义搜索与嵌入”）。

将结构化文档（研究报告、架构决策、事后分析）存储为可搜索的片段树：

# Store a markdown document — auto-parsed into typed fragments
memory_store_document(
    content="# Research Report\n\n## Evidence Table\n| Claim | Confidence |\n...",
    document_key="research/memora-enhancements-2026-04-08",
    tags=["memora/research"]
)
# Returns: {root_id: 230, fragment_count: 100, node_map: {claim: [...], plan_item: [...], ...}}

# Retrieve the full document or specific fragment types
memory_get_document(document_key="research/memora-enhancements-2026-04-08")
memory_get_document(document_key="...", node_kinds=["claim"], content_mode="full")

# Delete a document and all its fragments
memory_delete_document(document_key="research/memora-enhancements-2026-04-08")

**工作原理：**解析器会按结构拆分 Markdown——表格会拆分为单条声明，编号列表会拆分为计划条目，URL 列表会拆分为引用，风险章节会拆分为风险片段。每个片段都可以通过 memory_semantic_search 独立搜索，同时也可以将完整文档作为一个整体检索。

片段类型：claim、plan_item、reference、section_chunk、risk

**完整性保护：**文档片段受到保护，避免意外修改：

• 对片段调用 memory_delete 时必须设置 force=True
• memory_merge 拒绝合并片段
• memory_absorb 不会将片段纳入相似度匹配
• memory_find_duplicates 和 memory_detect_supersessions 会跳过片段
• 图形界面会隐藏片段，只显示文档根节点

用于常见记忆类型的结构化工具：

# Create a TODO with status and priority
memory_create_todo(content="Implement feature X", status="open", priority="high", category="backend")

# Create an issue with severity
memory_create_issue(content="Bug in login flow", status="open", severity="major", component="auth")

# Create a section placeholder (hidden from graph)
memory_create_section(content="Architecture", section="docs", subsection="api")

分析已存储的记忆并提取可执行的洞察：

# Full analysis with LLM-powered pattern detection
memory_insights(period="7d", include_llm_analysis=True)

# Quick summary without LLM (faster, no API key needed)
memory_insights(period="1m", include_llm_analysis=False)

返回：

• 活动摘要——该时间段内创建的记忆，按类型和标签分组
• 未完成事项——未完成的 TODO 和问题，并检测长期未处理的事项（可通过 MEMORA_STALE_DAYS 配置；memory_insights 默认为 14，图形界面默认为 30——两个使用方共用同一变量）
• 整合候选项——可能适合合并的相似记忆对
• LLM 分析——主题、重点领域、知识缺口和摘要（需要 OPENAI_API_KEY）

管理记忆之间的关系：

# Create typed edges between memories
memory_link(from_id=1, to_id=2, edge_type="implements", bidirectional=True)

# Edge types: references, implements, supersedes, extends, contradicts, related_to

# Remove links
memory_unlink(from_id=1, to_id=2)

# Boost memory importance for ranking
memory_boost(memory_id=42, boost_amount=0.5)

# Detect clusters of related memories
memory_clusters(min_cluster_size=2, min_score=0.3)

如需离线查看，可将记忆导出为静态 HTML 文件：

memory_export_graph(output_path="~/memories_graph.html", min_score=0.25)

此功能为可选项——实时图谱服务可通过实时更新提供相同的可视化效果。

使用 Telescope 直接在 Neovim 中浏览记忆。将插件复制到配置中：

# For kickstart.nvim / lazy.nvim
cp nvim/memora.lua ~/.config/nvim/lua/kickstart/plugins/

用法： 按 <leader>sm 打开记忆浏览器，使用模糊搜索和预览。

需要在 Python 环境中安装 telescope.nvim、plenary.nvim 和 memora。