# agendum — Full Documentation

> Project memory and scoping engine for AI coding agents.

## Overview

agendum is an MCP (Model Context Protocol) server that gives any AI agent persistent project state, scoped work packages, and cross-session continuity. It works with Claude Code, Cursor, Windsurf, VS Code (Copilot), Cline, Roo Code, and Claude Desktop.

All state is stored as human-readable Markdown files with YAML frontmatter in a `.agendum/` directory. Zero-config: auto-initializes on first tool call.

## Install

```
pip install agendum
uvx agendum --home serve
claude mcp add agendum -- uvx agendum --home serve
```

Requires Python 3.13+.

## Workflow

1. PLAN — Write or generate a markdown plan file
2. INGEST — `pm_ingest(project, plan_file)` parses plan into bounded board items
3. SCOPE — `pm_next(project)` returns enriched work package with complexity signals
4. EXECUTE — Agent implements the task within scoped boundaries
5. REPORT — `pm_done(project, item_id)` records completion with decisions and patterns
6. RESUME — `pm_status(project)` restores context, `pm_next(project)` continues

## Tools Reference

### pm_init

Initialize the agendum board directory.

Parameters:
- `name` (str, default: "agendum") — Board name

### pm_project

Create, list, or get projects.

Parameters:
- `action` (str, required) — "create", "list", or "get"
- `name` (str) — Project name (required for create/get)
- `description` (str) — Project description (for create)

### pm_status

Get status overview for one or all projects. Shows item counts by status, recent progress, recent decisions, and suggested next task.

Parameters:
- `project` (str) — Project name. Omit for all-project overview.

### pm_add

Add a new item to a project board.

Parameters:
- `project` (str, required) — Project name
- `title` (str, required) — Item title
- `type` (str, default: "dev") — dev, docs, ops, research, review, planning, personal, email
- `priority` (str, default: "medium") — critical, high, medium, low
- `tags` (str) — Comma-separated tags
- `depends_on` (str) — Comma-separated item IDs this depends on
- `acceptance_criteria` (str) — Comma-separated acceptance criteria
- `key_files` (str) — Comma-separated file paths
- `constraints` (str) — Comma-separated constraints
- `notes` (str) — Free-form notes

### pm_board

View the project board with optional filters.

Parameters:
- `project` (str, required) — Project name
- `status` (str) — Filter: pending, in_progress, blocked, done, review, cancelled
- `tag` (str) — Filter by tag
- `type` (str) — Filter by type

### pm_ingest

Import tasks from a markdown plan file into the project board. Parses headings as task titles, extracts acceptance criteria, key files, and dependencies.

Parameters:
- `project` (str, required) — Project name
- `plan_file` (str, required) — Path to markdown plan file

Plan format: `##` or `###` headings become tasks. Under each heading:
- `**Acceptance Criteria:**` followed by `- ` bullets
- `**Files:**` comma-separated file paths
- `**Depends:**` comma-separated references (e.g., "Task 1, Task 2")

### pm_next

Get the next scoped work package. Returns bounded context with task details, acceptance criteria, memory, dependency context, and project rules. Automatically marks the task as in-progress.

Parameters:
- `project` (str, required) — Project name

Returns a WorkPackage with complexity signal and enriched context.

### pm_done

Report task completion. Records decisions, patterns, and learnings to project memory. Auto-extracts git diff and commit info.

Parameters:
- `project` (str, required) — Project name
- `item_id` (str, required) — Item ID (e.g., "item-001")
- `decisions` (str) — Comma-separated architectural decisions
- `patterns` (str) — Comma-separated reusable patterns/conventions
- `files_changed` (str) — Files changed (auto-extracted from git if omitted)
- `notes` (str) — Free-form notes (auto-populated from last commit if omitted)
- `learnings` (str) — Comma-separated project-scoped learnings
- `verified` (bool, default: false) — Set true after running tests
- `verification_notes` (str) — What was verified and how
- `auto_extract` (bool, default: true) — Auto-extract from git diff/log

### pm_block

Report a task as blocked.

Parameters:
- `project` (str, required) — Project name
- `item_id` (str, required) — Item ID
- `reason` (str, required) — Why the task is blocked

### pm_memory

Read, write, append, or search project memory.

Parameters:
- `action` (str, required) — "read", "write", "append", or "search"
- `scope` (str) — Memory scope: "decisions", "patterns", "project", "learnings"
- `content` (str) — Content to write/append
- `query` (str) — Search query
- `author` (str) — Author attribution

### pm_learn

Record a learning (global or project-scoped).

Parameters:
- `content` (str, required) — The learning content
- `tags` (str) — Comma-separated tags for categorization
- `topics` (str) — Comma-separated entity/concept names for graph linking. Entries sharing 2+ topics are auto-linked in the entity graph.
- `source_project` (str) — Project where this was learned
- `project` (str) — Scope to a specific project (omit for global)
- `event_at` (str) — ISO datetime when the learning occurred (default: now)

### pm_search

Search all agendum knowledge using hybrid retrieval. Covers memory, learnings, and completed board items.

Uses three signals fused via Reciprocal Rank Fusion (RRF) with temporal reranking:
1. FTS5 full-text search with Porter stemming (always active)
2. Vector similarity via fastembed + sqlite-vec (active when `agendum[vectors]` is installed)
3. Entity graph expansion (entries linked by shared topics/tags)

Parameters:
- `query` (str, required) — Search query (supports natural language)
- `project` (str) — Filter to a specific project (omit to search globally)
- `source_type` (str) — Filter by type: "memory", "learning", or "board_item"
- `limit` (int, default: 10) — Maximum results to return

### pm_consolidate

Clean up memory and maintain knowledge quality. Runs automatically on corruption or duplicates.

- Strips XML/tool-call fragments leaked into memory scopes
- Finds near-duplicate learnings (same 50-char prefix) and marks extras superseded
- Rebuilds the FTS5 search index from source Markdown files
- Scans for potential contradictions via entity graph overlap

Parameters:
- `project` (str) — Scope cleanup to a specific project (omit for global)

### pm_supersede

Soft-invalidate a learning. The entry is preserved but excluded from all future searches.

Parameters:
- `entry_id` (str, required) — ID of the learning to supersede
- `project` (str) — Project scope (omit for global learnings)
- `reason` (str) — Why this learning is no longer valid
- `replacement_id` (str) — ID of the learning that replaces this one (creates a supersedes link in the entity graph)

## Data Model

### BoardItem

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| id | str | auto | Sequential ID (item-001, item-002, ...) |
| project | str | required | Parent project name |
| title | str | required | Item title |
| status | TaskStatus | pending | Current status |
| type | TaskType | dev | Task category |
| priority | TaskPriority | medium | Priority level |
| depends_on | list[str] | [] | IDs this item depends on |
| blocks | list[str] | [] | IDs this item blocks |
| acceptance_criteria | list[str] | [] | Exit conditions |
| key_files | list[str] | [] | Files to create/modify |
| constraints | list[str] | [] | Scope boundaries |
| tags | list[str] | [] | Categorization tags |
| notes | str | "" | Free-form notes |
| decisions | list[str] | [] | Architectural decisions made |
| verified | bool | false | Whether tests were run |
| progress | list[ProgressEntry] | [] | Timestamped progress log |

### WorkPackage

Returned by `pm_next`. Contains:
- `item` — The BoardItem being worked on
- `scope` — File scope description
- `exit_criteria` — What must be true when done
- `constraints` — Boundaries to stay within
- `key_files` — Files to create/modify
- `dependency_context` — Info from completed dependencies
- `memory_context` — Relevant project memory
- `project_rules` — Rules from CLAUDE.md / project config
- `complexity` — trivial, small, medium, or large
- `estimated_scope` — Human-readable scope description

### Enums

**TaskStatus:** pending, in_progress, blocked, review, done, cancelled
**TaskPriority:** critical, high, medium, low
**TaskType:** dev, docs, ops, research, review, planning, personal, email

## Complexity Budgets

Context enrichment scales with task complexity:

| Complexity | Total Budget | Project Rules | Dependencies | Memory |
|------------|-------------|---------------|--------------|--------|
| trivial | 4,000 chars | 1,500 | 1,000 | 1,000 |
| small | 6,000 chars | 2,000 | 1,500 | 1,500 |
| medium | 8,000 chars | 2,500 | 2,000 | 2,000 |
| large | 10,000 chars | 3,000 | 2,500 | 2,500 |

## Storage Layout

```
~/.agendum/
├── config.yaml
├── projects/
│   └── <project>/
│       ├── project.yaml
│       ├── board/
│       │   ├── item-001.md
│       │   └── item-002.md
│       └── learnings/
│           └── learning-001.md
├── learnings/
│   └── learnings.md
└── memory/
    ├── decisions.md
    ├── patterns.md
    ├── project.md
    └── learnings.md
```

Board items are Markdown files with YAML frontmatter. Human-readable, diffable, committable.

## Links

- [GitHub](https://github.com/sralli/agendum)
- [PyPI](https://pypi.org/project/agendum/)
- [License: MIT](https://github.com/sralli/agendum/blob/master/LICENSE)
