Metadata-Version: 2.4
Name: agent-supervisor-memory
Version: 0.1.1
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`）。

## Quickstart

```sh
cd mcp-tools/agent-supervisor-memory
poetry install
poetry run agent-supervisor-memory
```

默认存储文件：

- Memory：优先使用“最近的祖先目录中已存在的 `.codex/`”下的 `.codex/memory.json`；若不存在，则用 `<cwd>/.codex/memory.json`
- Policy：同理，默认 `.codex/agent-policy.json`

说明：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"]
```

说明：

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

### 常用开关

```toml
[mcp_servers.supervisor_memory]
command = "uvx"
args = ["agent-supervisor-memory", "--global-memory", "--global-policy"]
```

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

```toml
[mcp_servers.supervisor_memory]
command = "uvx"
args = ["agent-supervisor-memory", "--no-memory", "--no-subagents", "--no-policy"]
```

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

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

```sh
agent-supervisor-memory --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：`codex-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` 搜索关键字。

## Tools

- `capabilities_get`
- `policy_get`
- `memory_put`
- `memory_search`
- `memory_delete`
- `memory_compact`（生成 `profile.json`，把“杂乱记忆”压缩为分类摘要）
- `workflow_ensure_spec`
- `workflow_route`
- `subagents_echo`（示例）

