Agendum

agendum

面向 AI 编码 Agent 的项目记忆与范围管理引擎。

AI 编码 Agent 是无状态的——它们会在不同会话之间遗忘内容、丢失决策，也无法限定复杂工作的范围。agendum 是一款 MCP 服务，可为任何 Agent（Claude Code、Cursor、Windsurf、Cline 等）提供持久化项目状态、边界明确的工作包，以及跨会话连续性。

不使用 agendum	使用 agendum
Agent 会忘记不同会话之间的一切	从上次停下的地方准确继续
没有范围限制——Agent 会随意修改文件	工作包边界明确，包含文件列表、验收标准和约束条件
决策丢失——重复犯同样的错误	决策和模式会持久保存到可搜索的记忆中
没有任务排序——Agent 会随机选择	依赖关系图支持自动解除阻塞和优先级评分
学习成果被锁定在单个项目中	跨项目经验会将模式延续下去

快速开始

pip install agendum                                    # or: uvx agendum
claude mcp add agendum -- uvx agendum --home serve     # add to Claude Code
# Done. pm_* tools are now available in your agent.

可与任何 MCP 客户端配合使用——查看 Cursor、Windsurf、VS Code 等的设置方法。

工作原理

flowchart LR
    A["PLAN\nwrite plan file"] --> B["pm_ingest\nboard items + deps"]
    B --> C["pm_next\nwork package + context"]
    C --> D["EXECUTE\nagent implements"]
    D --> E["pm_done\ndecisions + patterns"]
    E -->|next task| C
    E -->|new session| F["pm_status\nresume context"]
    F --> C

每次 pm_done 都会记录决策和模式，丰富后续 pm_next 调用的内容——上下文会在不同会话间不断积累。

会话示例：

You: I have a plan file for the API rewrite. Ingest it.

Agent:
  → pm_ingest(project="api-rewrite", plan_file="plan.md")

  Ingested 4 board items from plan:
    item-001: Schema design [high]
    item-002: Resolver layer (depends on item-001)
    item-003: Auth middleware (depends on item-001)
    item-004: Integration tests (depends on item-002, item-003)

You: What should I work on?

Agent:
  → pm_next(project="api-rewrite")

  Work package for item-001 "Schema design":
    Context: project rules, memory from last session
    Scope: Define GraphQL schema types
    Acceptance criteria: Types for User, Product, Order

You: Done with the schema. Here's what I decided...

Agent:
  → pm_done(project="api-rewrite", item_id="item-001",
      decisions="Using code-first with Strawberry",
      patterns="N+1 queries need DataLoader",
      verified=True)

  Marked item-001 as done. Unblocked: item-002, item-003
  > Next: pm_next("api-rewrite") to continue with newly unblocked tasks

14 个 MCP 工具

设置与概览

工具	用途
pm_init	初始化看板目录（可选——首次使用时会自动初始化）
pm_project	创建、列出或获取项目
pm_status	仪表板——条目数量、近期进展、记忆状态、建议的下一项任务

规划与待办事项

工具	用途
pm_add	添加条目，并指定类型、优先级、标签、依赖项和验收标准
pm_board	查看和筛选项目看板
pm_ingest	将 Markdown 计划文件导入为边界明确、带有依赖项的看板条目

执行循环

工具	用途
pm_next	获取下一个范围明确的工作包，包含复杂度提示和增强上下文
pm_done	完成条目——记录决策、模式和经验；从 git 自动提取；自动解除依赖项的阻塞
pm_block	报告任务受阻并说明原因

知识与搜索

工具	用途
pm_memory	读取、写入、追加或搜索项目记忆（决策、模式、项目知识）
pm_learn	记录全局或特定项目的经验，并添加标签和主题实体
pm_search	对所有知识进行混合搜索——记忆、经验、已完成条目
pm_consolidate	清理记忆损坏内容、合并重复经验、检测矛盾
pm_supersede	将某条经验软失效——之后的所有搜索都会将其排除

混合搜索

pm_search 结合三种信号，从记忆、经验总结和已完成的看板事项中查找相关知识：

• 带 Porter 词干提取的 FTS5 — auth 可匹配 authentication，config 可匹配 configuration。始终启用，无需配置。
• 向量搜索 （可选） — 安装 agendum[vectors]，通过 fastembed + sqlite-vec 添加语义相似度搜索。会与 FTS5 一同自动启用。
• 实体图谱 — 主题和标签构成知识图谱。共享 2 个或更多实体的条目会自动关联。图谱扩展可呈现关键词搜索遗漏的相关知识。

这三种信号通过 Reciprocal Rank Fusion（RRF）融合，再根据新近度和访问频率重新排序。索引会根据 Markdown 文件重建——即使索引损坏，也不会丢失数据。

主要功能

• 自适应上下文预算 — 根据任务复杂度调整补充内容：简单任务为 4K 字符，大型任务最高为 10K 字符
• 验证关卡 — pm_done(verified=True) 可区分已测试和未经测试的完成项
• Git 自动提取 — 未指定文件时，pm_done 会自动读取 git diff 和 git log
• 可插拔的补充信息管道 — 每个工作包都会注入四种上下文来源：项目规则（CLAUDE.md/AGENTS.md）、记忆、依赖上下文和经验总结
• 依赖关系解析 — 使用拓扑排序并检测循环依赖；上游任务完成后，会自动解除对依赖任务的阻塞
• 记忆健康状况 — pm_status 会警告损坏的条目；pm_consolidate 会清除 XML 片段、去重并标记矛盾
• 零配置 — 首次调用工具时自动初始化，并从 git 远程仓库推导看板名称
• Git 原生存储 — 所有状态都以易读的 Markdown + YAML 格式存储在 .agendum/ 中，可比较差异并提交

安装

除 VS Code 外，所有 MCP 客户端都使用相同配置。请添加到相应文件中：

{
  "mcpServers": {
    "agendum": {
      "command": "uvx",
      "args": ["agendum", "--home", "serve"]
    }
  }
}

客户端	配置位置
Claude Code	运行：claude mcp add agendum -- uvx agendum --home serve
Cursor	项目根目录下的 .cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	Settings › MCP Servers › Edit
Roo Code	MCP 设置文件
Claude Desktop	claude_desktop_config.json

VS Code（GitHub Copilot）： 使用 "servers" 而不是 "mcpServers"。请添加到 .vscode/mcp.json：

{
  "servers": {
    "agendum": {
      "command": "uvx",
      "args": ["agendum", "--home", "serve"]
    }
  }
}

命令行（独立运行）

pip install agendum
agendum project create my-app   # Create a project
agendum status                  # Dashboard overview
agendum next my-app             # Suggest next task

存储布局

所有状态都存储在 ~/.agendum/ 中（如果偏好本地存储，也可存储在项目中的 .agendum/）：

~/.agendum/
├── .cache/
│   └── search.db               # FTS5 + vector search index (auto-rebuilt)
├── config.yaml
├── projects/
│   └── webapp/
│       ├── project.yaml         # Project metadata
│       ├── board/
│       │   ├── item-001.md      # Markdown + YAML frontmatter
│       │   └── item-002.md
│       └── learnings/           # Project-scoped learnings
│           └── learning-001.md
├── learnings/                   # Cross-project learnings
│   └── learning-001.md
└── memory/
    ├── decisions.md             # Key decisions + rationale
    └── patterns.md              # Discovered conventions

架构

src/agendum/
├── server.py              # MCP server wiring (FastMCP)
├── tools.py               # 14 MCP tools
├── models.py              # Pydantic models (BoardItem, WorkPackage, SearchResult)
├── task_graph.py          # Dependency resolution + topological levels
├── config.py              # Shared configuration
├── env_context.py         # Git diff/log auto-extraction
├── cli.py                 # CLI interface
├── enrichment/
│   ├── pipeline.py        # ContextEnricher, budget allocation
│   └── sources.py         # ProjectRules, Memory, Dependency, Learnings sources
└── store/
    ├── board_store.py     # BoardItem CRUD
    ├── board_format.py    # Markdown <-> BoardItem serialization
    ├── project_store.py   # Project metadata
    ├── memory_store.py    # Scoped memory storage
    ├── learnings_store.py # Global and project-scoped learnings
    ├── search_index.py    # FTS5 + vector + entity graph + RRF
    ├── embedding.py       # Lazy fastembed wrapper (optional)
    └── locking.py         # get_lock() + atomic_write()

开发

git clone https://github.com/sralli/agendum.git
cd agendum
uv sync
uv run pytest tests/ -v     # all tests
uv run ruff check .          # lint
uv run ruff format --check . # format check

许可证

MIT