Agendum

agendum

AI コーディングエージェント向けのプロジェクトメモリとスコープ管理エンジンです。

AI コーディングエージェントはステートレスです。セッション間で内容を忘れ、決定事項を失い、複雑な作業の範囲を定める手段がありません。agendum は、あらゆるエージェント（Claude Code、Cursor、Windsurf、Cline など）に永続的なプロジェクト状態、範囲を限定した作業パッケージ、セッションをまたいだ継続性を提供するMCP サーバーです。

agendum なし	agendum あり
エージェントはセッション間ですべてを忘れる	中断したところから正確に再開できます
スコープがなく、エージェントが無関係なファイルを変更する	ファイル一覧、受け入れ基準、制約を含む、範囲が限定された作業パッケージ
決定事項が失われ、同じ間違いが繰り返される	決定事項やパターンが検索可能なメモリに保存されます
タスクの順序がなく、エージェントがランダムに選ぶ	自動ブロック解除と優先度スコアリングを備えた依存関係グラフ
学びが1つのプロジェクト内に閉じ込められる	プロジェクトをまたいで学びが共有され、パターンが引き継がれます

クイックスタート

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 は、メモリ、学習事項、完了済みのボード項目から関連するナレッジを見つけるために、3 つのシグナルを組み合わせます。

• Porter ステミングを使用した FTS5 — auth で authentication が、config で configuration が見つかります。常に有効で、設定は不要です。
• ベクトル検索 (任意) — agendum[vectors] をインストールすると、fastembed と sqlite-vec による意味的類似性検索を追加できます。FTS5 とともに自動的に有効になります。
• エンティティグラフ — トピックとタグがナレッジグラフを形成します。2 つ以上のエンティティを共有する項目は自動的にリンクされます。グラフの展開により、キーワード検索では見つからない関連ナレッジも表示されます。

3 つのシグナルは Reciprocal Rank Fusion（RRF）で統合された後、直近性とアクセス頻度に基づいて再ランク付けされます。インデックスは Markdown ファイルから再構築されるため、破損してもデータは失われません。

主な機能

• 適応型コンテキスト予算 — タスクの複雑さに応じて情報の追加量を調整します。単純なタスクでは 4K 文字、大規模なタスクでは最大 10K 文字です。
• 検証ゲート — pm_done(verified=True) により、テスト済みの完了と未テストの完了を区別します。
• Git による自動抽出 — ファイルが指定されていない場合、pm_done は git diff と git log を自動的に読み取ります。
• プラグイン可能な情報追加パイプライン — 4 つのコンテキストソースをすべての作業パッケージに注入します。プロジェクトルール（CLAUDE.md/AGENTS.md）、メモリ、依存関係のコンテキスト、学習事項です。
• 依存関係の解決 — 循環検出を備えたトポロジカル順序付けに対応し、上流タスクが完了すると依存タスクのブロックが自動的に解除されます。
• メモリの健全性 — pm_status は破損したエントリを警告し、pm_consolidate は XML 断片を除去し、重複を排除して、矛盾を検出します。
• 設定不要 — 最初のツール呼び出し時に自動初期化し、Git リモートからボード名を導き出します。
• Git ネイティブのストレージ — すべての状態は .agendum/ 内の人が読める Markdown と YAML で保存され、差分を確認してコミットできます。

インストール

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）： "mcpServers" ではなく "servers" を使用します。.vscode/mcp.json に追加してください。

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

CLI（単体）

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