TMCRA Agent Memory

TMCRA MCP Server

TMCRA MCP Server 为 MCP 主机提供对 Agent 长期记忆的明确访问权限。它可回忆项目证据、写入带有说话者归属的真实对话记录、保留多 Agent 项目范围，并跟踪异步写入直至终态。

中文说明

提供的功能

• 跨会话项目连续性。 从一个稳定的项目范围中回忆有限的证据。
• 跨工具协作。 不同 MCP 主机可以使用相同范围，同时保留各自的会话来源信息。
• 说话者和 Agent 归属。 用户、助手、系统和工具记录彼此独立；已知的 Agent 记录者或目标仍会附加到记录上。
• 明确的轮次生命周期。 主机可以在回答前准备回忆，并在之后提交确切的用户/助手轮次。
• 持久化写入恢复。 传输不确定时会进入本地 SQLite 队列，并进行幂等协调。
• 可验证的回执。 回忆、摄取和作业响应会在返回给 MCP 主机前经过验证。
• 九个 MCP 工具。 回忆、摄取、准备、提交、协调、获取作业、等待作业、会话记忆控制和定向反馈。

tmcra_memory_control 提供任务选择、默认 12000 字符的回忆预算，以及 normal、recall_only、off 模式。向回忆/准备和控制操作传入完全相同的 session_id。模式更改后会丢弃较早的待处理代次；已提交的作业仍保持已提交状态。tmcra_feedback 支持 ignore、correct（用户提供替换内容）和带稳定幂等键的 restore。反馈只有在匹配的后端更新成功后才会生效；请单独检查 correction_index_status。可视化控制面板由 Codex 和 DSH 发行版提供。此 MCP 软件包会自动发现共享的本地安装；仅在明确指定本地身份时才允许使用数字环回 HTTP。托管连接必须使用 HTTPS。

对话中的更正现在需要主机交互确认。收到实际的更正请求时，请在澄清或反馈之前调用 tmcra_memory_control(operation="correction_start")，以禁止自动捕获该讨论轮次。tmcra_feedback 会读取确切的原始证据，并使用 MCP 表单征询展示来源、替换内容和范围；只有明确接受后才会提交反馈。拒绝、取消、过期或主机不受支持时，记忆都不会改变。不要用摄取操作替代被拒绝的更正。主机生命周期轮次 ID 可防止后续队列重放影响该讨论，同时保留其他已识别轮次。第三方主机必须将征询转发给用户；服务端无法保证任意客户端不会自动作答。假设性或引用的更正措辞不构成授权。

通用 MCP 客户端会自行决定何时调用工具。仅连接此服务并不会自动感知主机的回答前或回答后生命周期。如需自动执行 Codex 回忆和捕获，请安装单独的 TMCRA Codex Memory 插件。

安装

MCPB 发布

从 v1.0.0-rc.1 发布页下载 tmcra-mcp-server-1.0.0-rc.1.mcpb，并在兼容 MCPB 的客户端中打开。此捆绑包使用跨平台 uv 运行时。托管服务用户需在敏感字段中输入 API 密钥。如需在 Windows 上使用无需账户的本地记忆功能，请解压独立运行时，双击 Install-Local.cmd，然后重启 MCP 宿主。本地身份会自动发现，并覆盖表单中的云端 URL/密钥；使用此模式时，请将 API 密钥留空。显式设置的高级 TMCRA_CONFIG_FILE 仍具有最高优先级。本地模型的接受限制记录在运行时发布说明中。

Python wheel

python -m pip install \
  https://github.com/reshuibuduo/tmcra-mcp-server/releases/download/v1.0.0-rc.1/tmcra_mcp_server-1.0.0rc1-py3-none-any.whl

通过 uvx 直接从 GitHub 安装

uvx --from "git+https://github.com/reshuibuduo/[email protected]" tmcra-mcp

授权

创建 TMCRA 账户和 API 密钥，然后通过 MCP 客户端的机密存储或 TMCRA_API_KEY 环境变量提供。请勿将凭据提交到代码仓库。

TMCRA_API_KEY=<your TMCRA API key>
TMCRA_BASE_URL=https://api.tmcra.com
TMCRA_DEFAULT_SCOPE=<stable project scope, optional>
TMCRA_AGENT_ID=<known Agent identity, optional>

通过 TMCRA 应用登录的用户也可以使用其受保护的设备文件 ~/.config/tmcra/config.json。开发者配置和可自托管配置中，环境变量的优先级高于该文件。

服务仅接受不含嵌入式凭据、查询字符串或片段的 HTTPS API 源地址。

注册到 MCP 宿主

安装 wheel 后，MCP 宿主可以启动：

{
  "mcpServers": {
    "tmcra-memory": {
      "command": "tmcra-mcp",
      "env": {
        "TMCRA_API_KEY": "<stored securely by the host>",
        "TMCRA_DEFAULT_SCOPE": "project-example"
      }
    }
  }
}

此软件包还包含 Codex 设置助手：

tmcra-mcp-setup install --mode explicit
tmcra-mcp-setup status --mode explicit

工具

工具	用途
tmcra_memory_control	检查或显式更改会话模式、任务和回忆预算。
tmcra_feedback	预览确切的证据，并在提供有针对性的反馈前请求交互式确认。
tmcra_recall	针对当前查询，最多返回 8 个可直接用于提示词的证据窗口。
tmcra_ingest	持久化已发生的消息，并保留角色和 Agent 归属信息。
tmcra_turn_prepare	在回答前检索记忆，并可靠地绑定实际用户轮次。
tmcra_turn_commit	将准备好的用户轮次和确切的助手回答作为独立记录持久化。
tmcra_reconcile	使用相同的幂等键重试可靠保存的待处理记录。
tmcra_get_job	读取单个异步写入任务的状态。
tmcra_wait_job	等待任务成功、失败或取消。

每位项目协作者都应使用相同的项目 scope。每段对话都使用各自的 session_id。Agent 身份用于归属标记，不会拆分项目记忆。

检索到的内容会带有 trust_boundary: untrusted_memory_data。宿主必须将其视为证据，而非可执行指令。

显式生命周期

需要维持逐轮连续性的 MCP 宿主应：

1. 收到当前用户问题后，调用 tmcra_turn_prepare。
2. 仅将返回的 injectable_context 作为不可信证据注入。
3. 起草回答。
4. 使用相同的 turn_id 和确切的最终回答调用 tmcra_turn_commit。
5. 如实报告待处理或终态写入状态。

较低层级的等效流程为 tmcra_recall、回答、tmcra_ingest，然后调用 tmcra_get_job 或 tmcra_wait_job。

安全边界

• 凭据从环境变量或受保护的 TMCRA 设备文件中读取，服务绝不会打印凭据。
• API 目标地址必须使用 HTTPS。
• 结构化回执会拒绝格式错误的检索、写入和任务响应。
• 检索到的记忆仍是不可信数据。
• 此代码仓库仅包含客户端 MCP 集成，不包含生产服务源代码或生产凭据。
• 此工具集不提供破坏性记忆删除和导出功能。

漏洞报告请参阅 SECURITY.md。

开发

python -m pip install -e ".[dev]"
python -m pytest -q
python -m build
python -m twine check dist/*

测试涵盖回执验证、范围和执行者语义、持久化队列恢复、配置安全、设置行为，以及真实的 MCP 初始化/列表/调用冒烟测试。

License

Apache-2.0. See LICENSE and NOTICE.