# agendum

> Project memory and scoping engine for AI coding agents.

## Overview

MCP server that gives any AI agent persistent project state, scoped work packages, and cross-session continuity. All state is git-native Markdown + YAML in a `.agendum/` directory.

## Install

- `pip install agendum`
- `uvx agendum --home serve`
- Claude Code: `claude mcp add agendum -- uvx agendum --home serve`

## Workflow

1. **PLAN** — Write or generate a plan file
2. **INGEST** — `pm_ingest` reads plan, creates bounded board items with dependencies
3. **SCOPE** — `pm_next` returns a work package with complexity signals and enriched context
4. **EXECUTE** — Agent works within the scoped package
5. **REPORT** — `pm_done` records completion, decisions, patterns, learnings
6. **RESUME** — Next session: `pm_status` to restore context, `pm_next` to continue

## Tools

- `pm_init` — Initialize board directory
- `pm_project` — Create, list, or get projects
- `pm_status` — Board overview with item counts, recent progress, suggested next task
- `pm_add` — Add item with type, priority, tags, dependencies, acceptance criteria
- `pm_board` — View and filter the project board
- `pm_ingest` — Import markdown plan file into bounded board items
- `pm_next` — Get next scoped work package with enriched context
- `pm_done` — Complete item, record decisions/patterns/learnings, auto-extract git info
- `pm_block` — Report task as blocked with reason
- `pm_memory` — Read, write, append, or search project memory
- `pm_learn` — Record global or project-scoped learnings with tags and topic entities
- `pm_search` — Hybrid search across all knowledge (memory, learnings, completed items)
- `pm_consolidate` — Clean memory corruption, deduplicate learnings, detect contradictions
- `pm_supersede` — Soft-invalidate a learning, excluded from all future searches

## Key Concepts

- **Work packages** — Bounded context with complexity signals (trivial/small/medium/large)
- **Enrichment pipeline** — Injects project rules, memory, dependency context, learnings
- **Hybrid search** — FTS5 (BM25) + optional vector search + entity graph, fused via RRF with temporal reranking
- **Dependency resolution** — Topological ordering, auto-unblock on completion
- **Git-native storage** — Human-readable `.agendum/` directory, diffable and committable

## Links

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