Metadata-Version: 2.4
Name: agent-supervisor-memory
Version: 0.1.0
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

# MCP tools (workflow + memory)

本目录提供一个 **单进程** 的 Python MCP server，默认启用两组能力：

- `workflow.*`: 生成最小化 spec（lite/spike/heavy）
- `memory.*`: 个人记忆（JSON 存储，关键词+tags+key 命名空间检索；无向量数据库/无 embedding）

MCP server 名称：`agent-supervisor-memory`（见 `mcp-tools/agent-supervisor-memory/server.py`）。

## Quickstart

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

默认存储文件：优先使用仓库根目录的 `.codex/memory.json`（可用 `MCP_MEMORY_PATH` 覆盖）。
默认策略文件：优先使用仓库根目录的 `.codex/agent-policy.json`（可用 `MCP_AGENT_POLICY_PATH` 覆盖）。

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

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

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

- `command`: `agent-supervisor-memory`
- `args`: `[]`

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

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

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

```toml
[mcp_servers.codex_tools]
command = "agent-supervisor-memory"
args = []
```

建议同时设置工作目录到仓库根目录（不同 client 字段名可能是 `cwd`/`workdir`/`root`），并按需加环境变量：

```toml
[mcp_servers.codex_tools]
command = "agent-supervisor-memory"
args = []
# cwd = "/path/to/k3s-test"
# env = { MCP_MEMORY_ENABLED = "true", MCP_SUBAGENTS_ENABLED = "true" }
```

### 安装方式（发布后）

- 推荐：`pipx install agent-supervisor-memory`，MCP client 用 `command="agent-supervisor-memory"`.
- 零安装：`uvx agent-supervisor-memory`，MCP client 用 `command="uvx" args=["agent-supervisor-memory"]`.

## 配置

环境变量（均为可选）：

- `MCP_MEMORY_ENABLED`：默认 `true`
- `MCP_SUBAGENTS_ENABLED`：默认 `true`（当前仅暴露示例 `subagents.echo`，便于后续扩展）
- `MCP_MEMORY_GLOBAL`：默认 `false`；设为 `true` 时默认改用 XDG 全局路径（`~/.local/share/agent-supervisor-memory/memory.json`）
- `MCP_MEMORY_PATH`：默认 `<repo>/.codex/memory.json`
- `MCP_MEMORY_MAX_ITEMS`：默认 `500`
- `MCP_MEMORY_MAX_BYTES`：默认 `2000000`（约 2MB）
- `MCP_POLICY_GLOBAL`：默认 `false`；设为 `true` 时默认改用 XDG 全局路径（`~/.config/agent-supervisor-memory/agent-policy.json`）
- `MCP_AGENT_POLICY_PATH`：默认 `<repo>/.codex/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`

## Tools

- `capabilities_get`
- `policy_get`
- `memory_put`
- `memory_search`
- `memory_delete`
- `workflow_ensure_spec`
- `workflow_route`
- `subagents_echo`（示例）

