# MindMemOS MCP

> 私有长期记忆库的远程 MCP 与 durable completed-turn ingestion 入口。

## Endpoints

- MCP tools: https://memory.nexora.restry.cn/mcp
- Reliable turn ingestion: https://memory.nexora.restry.cn/ingest/turn
- Health: https://memory.nexora.restry.cn/health
- This document: https://memory.nexora.restry.cn/llms.txt
- Companion skill: https://memory.nexora.restry.cn/skills/mindmemos-memory/SKILL.md

## Authentication and identity

所有 MCP 与 ingestion POST 请求都必须携带 `Authorization: Bearer <KEY>`。
Key 由库主人在内网面板签发；公网没有 issuance/bootstrap 路由。

**每个 Agent + 机器实例必须使用独立 Key。** Key 对应服务端拥有的 stable `client_id`、
`agent_kind`、`instance`、credential id、display name 和 scope。轮换 Key 时复用同一个
`client_id`；不要在工具参数或 hook payload 中自报 `client`、`app_id` 或 `agent_id`。

## Three integration layers

1. **MCP tools**：提供检索和显式写入。
2. **Companion Skill**：教 Agent 何时 `whoami` / `recall` / `project_rules` / `remember`；
   Skill 不能保证每个 Agent 自动执行。
3. **Optional runtime adapter**：completed-turn hook 的可靠自动写入层。需要自动捕获时安装；
   它不替代 MCP 召回或高价值事实的显式 `remember`。

## Tools

- `recall` — 检索 company 的长期记忆库（MindMemOS）：过往项目历史、技术决策、踩过的坑、偏好、约束与运维细节。回答任何涉及『我们之前怎么做的』『某项目的约束是什么』时先查这里。
- `remember` — 把一条值得长期保留的事实写入 MindMemOS 记忆库。
- `memory_stats` — 查看 MindMemOS 记忆库当前条数。
- `related_entities` — 在记忆图谱里查某个实体（项目名/人名/工具名）与什么关联最紧密，按共现次数排序。用于发现自己没想到的关联线索——比如查一个项目会带出它依赖的工具、涉及的组织、相关的其他项目。
- `project_rules` — 一次性列出某个项目的全部约束、铁律、禁止事项和已知限制。**在动手改某个项目的代码前先调这个**，避免踩已经记录过的坑。比 recall 更聚焦，会优先返回明确提到该项目名的记忆。
- `whoami` — 了解组织上下文：组织与团队、项目与业务、工作环境、协作规范。**新会话开始时、或需要了解组织背景时先调这个**——信息散落在多种记忆类型里，这个工具按公司维度聚合。

## Companion Skill

接入 Agent 应获取并阅读 `https://memory.nexora.restry.cn/skills/mindmemos-memory/SKILL.md`，再按自身 runtime 的原生 skill、extension 或
persistent-instruction 机制安装。安装位置由调用方决定；本文件不假设固定客户端路径。

## Optional runtime adapters

提供 Hermes、Claude Code 与 Pi/OMP 适配器。适配器只提交最新完成的 user message 与
final assistant message；默认不提交 thinking、tool calls、tool results 或完整 transcript。
本地 durable spool 负责短暂断网重试，服务端在 SQLite ledger 持久化事件后才返回 202。

Claude Code 适配器配对 `UserPromptSubmit` 与 `Stop`，Pi/OMP 使用 `agent_end`（不是
`turn_end`）。安装器不会替调用方修改 live settings；调用方应审阅 machine-readable
snippet，并把实例专属 Key 放进自己的 secret store。

Adapter ingestion payload：

```json
{
  "event_id": "stable-id",
  "session_id": "session-id",
  "turn_id": "turn-id",
  "user_message": "...",
  "assistant_message": "...",
  "started_at": "optional ISO/epoch",
  "completed_at": "optional ISO/epoch",
  "safe_context": {"runtime": "optional non-sensitive context"}
}
```

Producer identity、`app_id`、`agent_id`、authority 与 `capture_mode=auto_hook` 均由服务端
根据 Key 注入。重复 `event_id` + 相同 payload 幂等；同 ID 不同 payload 返回 409。

## Provenance semantics

每条语义记忆保存 `origin`、所有 `contributors` 与 `last_source`。后续 UPDATE、
REINFORCEMENT 或 MERGE 会加入新贡献者，不覆盖原始来源。`capture_mode` 独立于 Agent
身份和 authority，值包括 `auto_hook`、`explicit_remember`、`import`。

## Client-neutral MCP registration

```text
Name: mindmemos
Transport: Streamable HTTP
Endpoint: https://memory.nexora.restry.cn/mcp
Authentication: HTTP bearer token
```

调用方自行决定 MCP 配置与 Skill/extension 安装位置、Key 的 secret store 以及作用域。
默认使用 read Key；`remember` 或 runtime adapter 需要 write Key。

## Recommended behavior

- 新会话开始调用 `whoami`
- 回答既有项目/决策/踩坑前调用 `recall`；改项目前调用 `project_rules`
- 关键纠正、偏好、决策与可复用解法当场 `remember`，服务端会与 hook 捕获去重
- 不把 Key 写入聊天、源码、仓库、hook payload 或日志

## Security boundary

公网 :8765 只提供 `/mcp`、authenticated ingestion、`/llms.txt`、`/health` 和只读 Skill。
它不提供 token issuance；`/api/tokens/*` 只存在于内网 :8666 面板。