Metadata-Version: 2.4
Name: agent-supervisor-memory
Version: 0.2.5
Summary: Local-first MCP tools: workflow routing/spec + keyword memory (JSON) with optional toggles.
License: MIT
License-File: LICENSE
Author: agent-supervisor-memory contributors
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: mcp (==1.25.0)
Project-URL: Homepage, https://example.invalid/replace-me
Description-Content-Type: text/markdown

# agent-supervisor-memory (MCP server)

本目录提供一个 **单进程** 的 Python MCP server（stdio），默认启用：

- `workflow_*`: 生成最小化 spec（lite/spike/heavy）+ 路由建议（模型/effort）
- `memory_*`: 个人记忆（JSON 存储，关键词+tags+key 命名空间检索；无向量数据库/无 embedding）

MCP server ID：`agent-supervisor-memory`（见 `mcp-tools/agent-supervisor-memory/src/agent_supervisor_memory/server.py`）。

代码结构（便于加载更小的上下文）：
- `server.py`: 仅做配置解析与工具注册 wiring
- `dispatch_tools.py`: codex_dispatch_*（轮询/summary-only/尾部裁剪等）
- `memory_tools.py`: memory_*（JSON 存储 + compact 摘要）
- `workflow_tools.py`: workflow_* 与 subagents_echo
- `core_tools.py`: capabilities_get/policy_get

## Quickstart

```sh
cd mcp-tools/agent-supervisor-memory
poetry install
poetry run agent-supervisor-memory --dispatch-dir "$HOME/.codex/codex-dispatch"
```

默认存储文件：

- Memory：优先使用“最近的祖先目录中已存在的 `.codex/`”下的 `.codex/memory.json`；若不存在，则用 `<cwd>/.codex/memory.json`
- Policy：同理，默认 `.codex/agent-policy.json`
- Dispatch：`--dispatch-dir` 指定一个 **base 目录**，server 会按项目自动分桶：
  - `<dispatch-dir>/<project_bucket>/<job_id>/{meta.json,stdout.jsonl,stderr.log,last_message.txt}`
  - `project_bucket` 会尽量从 `codex_dispatch_start(cwd=...)` 的 cwd 向上推断（优先 `.codex/`，其次 `.git/`），并用 hash 保证稳定且不会太长
  - `job_id` 形如 `<project_bucket>--<uuid>`

说明：Poetry 会统一管理虚拟环境与依赖，避免你本机 shell 的 `python/pip` alias 干扰。

## 如何引用（MCP client 注册）

不同 MCP client 的配置方式不同，但核心信息通常是：

- `command`: `uvx`
- `args`: `["agent-supervisor-memory", "...flags"]`

工具名引用方式是 `tool name`，例如：`memory_search`、`workflow_route`。

### 参考配置片段（TOML 风格）

如果你的 client 支持类似下面这种配置（你贴的 `exa` 例子就是这种风格），可以这样写：

```toml
[mcp_servers.supervisor_memory]
command = "uvx"
args = ["agent-supervisor-memory", "--dispatch-dir", "/ABS/PATH/TO/.codex/codex-dispatch"]
```

说明：

- `[mcp_servers.supervisor_memory]` 里的 `supervisor_memory` 是 **client 侧别名**，你可以随便取（只要不跟别的 server 重名）。
- 是否“唯一”由你的 client 配置决定；PyPI 包名的唯一性是另一层（发布时）。

### 常用开关

```toml
[mcp_servers.supervisor_memory]
command = "uvx"
args = ["agent-supervisor-memory", "--dispatch-dir", "/ABS/PATH/TO/.codex/codex-dispatch", "--global-memory", "--global-policy"]
```

关闭某些能力（默认都是启用）：

```toml
[mcp_servers.supervisor_memory]
command = "uvx"
args = ["agent-supervisor-memory", "--dispatch-dir", "/ABS/PATH/TO/.codex/codex-dispatch", "--no-memory", "--no-subagents", "--no-policy"]
```

### 高级覆盖（一般不需要）

为兼容少数 client 场景，仍保留路径覆盖参数（优先级最高；不建议作为默认配置）：

```sh
agent-supervisor-memory --dispatch-dir /abs/path/to/codex-dispatch --memory-path /abs/path/to/memory.json --policy-path /abs/path/to/agent-policy.json
```

每次 tool 调用也可传：

- `options.enable_memory`: `true|false`
- `options.enable_subagents`: `true|false`

## 模型与模式（跨模型路由）

本 server **不直接调用模型**；它只提供“建议路由”，由你的 Supervisor/Client 负责真正使用什么模型去执行。

- `policy_get`: 读取策略文件
- `workflow_route`: 根据任务文本 + `mode/effort/auto` 给出建议的 `supervisor_model/coder_model/effort`

默认配置：

- Supervisor：`codex-5.2`
- Coder：`gpt-5.1-codex-max`
- `saving`：默认 `effort=medium`
- `efficient`：默认 `effort=medium`

## 如何确认正在使用（VSCode/其他 client）

- 调用 `capabilities_get`，查看返回里的 `memory.mode` / `policy.mode`（`project|global|disabled`）以及落盘 `path`。
- 写入/检索验证：`memory_put` 写入一条，然后 `memory_search` 搜索关键字。

## VSCode：自动“主/子模型”分工（推荐）

如果你同时启用了：

- `mcp__supervisor_memory__*`（本 server 的 tools）
- `mcp__codex__codex` / `mcp__codex__codex-reply`（Codex MCP）

那么可以在一个 Supervisor 会话里自动启动 Coder 子会话，并显式指定 coder 使用 `model=gpt-5.1-codex-max`（或按策略自动选择）：

1) 生成最小 spec（供 coder 执行）：
- 调用 `mcp__supervisor_memory__workflow_ensure_spec`（输入你的任务文本）

2) 获取路由建议（选择 coder 模型与 effort）：
- 调用 `mcp__supervisor_memory__workflow_route`（`task_text` 传上一步的 spec）

3) 启动 coder 子会话并执行：
- 调用 `mcp__codex__codex`，并设置：
  - `cwd`: 项目根目录
  - `model`: 上一步返回的 `coder_model`
  - `prompt`: spec + 约束（例如：只做必要改动、不要跑 build gate、先做最小校验）

4) 迭代直至完成：
- 用 `mcp__codex__codex-reply`（`conversationId` 为上一步返回）继续

### 如果 `mcp__codex__codex` 超时/返回类型不兼容

部分环境下，Codex MCP tool 可能会遇到 tool-call 超时（例如 60s）或 “Unexpected response type”。
此时可以改用本 server 自带的 dispatch 工具：它会在本机启动 `codex exec` 作为后台任务，并通过轮询查询结果。

流程：

1) 启动任务（内部记录 `job_id`，可按需返回）：
- 调用 `codex_dispatch_start`（`model` 用 `workflow_route` 返回的 `coder_model`；`cwd` 为项目根目录；`prompt` 传 spec）
- 默认返回 `{state:\"running\", message:\"Dispatch started\"}`；如需直接拿到 `job_id`，传 `options={\"return_job_id\":true}`；如需 artifacts/job 目录等完整字段，请传 `options={\"verbosity\":\"full\"}`。

2) 轮询结果：
- 调用 `codex_dispatch_status(job_id=... 可省略)` 直到 `state` 变为 `completed|failed`（默认仅回传最小字段）
- 默认输出最小化：运行/完成返回 `{state, message}`（`message` 为提取后的“最后一条用户可读消息”，非原始 JSONL）；失败返回 `{state:'failed', exit_code?, message}`（message 优先 stderr 摘要）；未找到返回 `{state:'not_found'}`。默认不会返回 `job_id` / `meta` / `artifacts` / `last_message`；若需原始 JSONL/full meta，请用 `options={\"verbosity\":\"full\"}`。
- 默认 tail 读取约 6KB 的 stdout/stderr（可通过 `stdout_tail_bytes`/`stderr_tail_bytes` 调整）；需要完整日志时，请使用 full 模式。
- `job_id` 参数可选：缺省时自动使用 server 进程内记录的上一次 `codex_dispatch_start` job；若没有记录，会返回 `{state:\"error\", message:\"job_id required\"}`。
- 如需原始/完整响应（含 `meta`/`artifacts`/`last_message` 等），请传 `options={\"verbosity\":\"full\"}` 或 `options={\"verbose\":true}`，或在启动 server 时设置 `SUPERVISOR_MEMORY_VERBOSE=1`（或 `SUPERVISOR_MEMORY_VERBOSITY=full`）。
- 批量等待：`codex_dispatch_wait_all(job_ids? , options?)` 默认 summary-only（只返回 `{state, job_ids, counts}` 并跳过 stdout/stderr tail）；若需 jobs 详情/last_message/artifacts，传 `options={\"summary_only\":false}`。

## Tools

- `capabilities_get`
- `policy_get`
- `memory_put`
- `memory_search`
- `memory_delete`
- `memory_compact`（生成 `profile.json`，把“杂乱记忆”压缩为分类摘要）
- `workflow_ensure_spec`
- `workflow_route`
- `subagents_echo`（示例）
- `codex_dispatch_start`（启动 `codex exec` 后台任务）
- `codex_dispatch_status`（轮询任务状态/输出）

## 发布到 PyPI（维护者）

PyPI 不允许覆盖已发布的同版本号，所以每次发布前都需要 bump version。

```sh
cd mcp-tools/agent-supervisor-memory

# 1) bump version（示例：0.1.0 -> 0.1.1）
poetry version patch

# 2) build
poetry build

# 3) publish（推荐用 token）
poetry publish -u __token__ -p "$PYPI_TOKEN"
```

可选：发布到 TestPyPI（先验证安装/依赖/元数据）：

```sh
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi -u __token__ -p "$TESTPYPI_TOKEN"
```

