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.

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

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

{
  "mcpServers": {
    "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/
├── .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