Metadata-Version: 2.4
Name: agendum
Version: 0.3.2
Summary: Universal project management for AI coding agents — MCP server + CLI + git-native task board
Project-URL: Homepage, https://github.com/sralli/agendum
Project-URL: Repository, https://github.com/sralli/agendum
Project-URL: Issues, https://github.com/sralli/agendum/issues
Author: Shivam Ralli
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,cli,mcp,model-context-protocol,project-management
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: click>=8.0
Requires-Dist: filelock>=3.13
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: vectors
Requires-Dist: fastembed>=0.4.0; extra == 'vectors'
Requires-Dist: sqlite-vec>=0.1.0; extra == 'vectors'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.sralli/agendum -->

# agendum

[![PyPI version](https://img.shields.io/pypi/v/agendum.svg)](https://pypi.org/project/agendum/)
[![Downloads](https://img.shields.io/pypi/dm/agendum.svg)](https://pypi.org/project/agendum/)
[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://github.com/sralli/agendum/actions/workflows/ci.yml/badge.svg)](https://github.com/sralli/agendum/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**Project memory and scoping engine for AI coding agents.**

AI coding agents are stateless — they forget between sessions, lose decisions, and have no way to scope complex work. agendum is an [MCP server](https://modelcontextprotocol.io/) that gives any agent (Claude Code, Cursor, Windsurf, Cline, and others) persistent project state, bounded work packages, and cross-session continuity.

| Without agendum | With agendum |
|---|---|
| Agent forgets everything between sessions | Picks up exactly where it left off |
| No scope — agent modifies random files | Bounded work packages with file lists, acceptance criteria, constraints |
| Decisions lost — same mistakes repeated | Decisions and patterns persist in searchable memory |
| No task ordering — agent picks randomly | Dependency graph with auto-unblocking and priority scoring |
| Learning locked inside one project | Cross-project learnings carry patterns forward |

## Quick Start

```bash
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.
```

Works with any MCP client — [see setup for Cursor, Windsurf, VS Code, and others](#installation).

## How It Works

```mermaid
flowchart LR
    A["1. PLAN\nWrite a plan file"] --> B["2. INGEST\npm_ingest → board items"]
    B --> C["3. SCOPE\npm_next → work package"]
    C --> D["4. EXECUTE\nAgent implements"]
    D --> E["5. REPORT\npm_done → decisions, patterns"]
    E --> C
    E --> F["6. RESUME\npm_status → pm_next\nnext session"]
    F --> C
```

Each `pm_done` records decisions and patterns that enrich future `pm_next` calls — context compounds across sessions.

**Example session:**

```
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 Tools

### Setup & Orientation

| Tool | Purpose |
|------|---------|
| `pm_init` | Initialize board directory (optional — auto-initializes on first use) |
| `pm_project` | Create, list, or get projects |
| `pm_status` | Dashboard — item counts, recent progress, memory health, suggested next task |

### Planning & Backlog

| Tool | Purpose |
|------|---------|
| `pm_add` | Add an item with type, priority, tags, dependencies, acceptance criteria |
| `pm_board` | View and filter the project board |
| `pm_ingest` | Import a Markdown plan file into bounded board items with dependencies |

### Execution Loop

| Tool | Purpose |
|------|---------|
| `pm_next` | Get the next scoped work package with complexity signal and enriched context |
| `pm_done` | Complete an item — record decisions, patterns, learnings; auto-extract from git; auto-unblock dependents |
| `pm_block` | Report a task as blocked with reason |

### Knowledge & Search

| Tool | Purpose |
|------|---------|
| `pm_memory` | Read, write, append, or search project memory (decisions, patterns, project knowledge) |
| `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 |

## Hybrid Search

`pm_search` combines three signals to find relevant knowledge across memory, learnings, and completed board items:

- **FTS5 with Porter stemming** — `auth` matches `authentication`, `config` matches `configuration`. Always on, zero config.
- **Vector search** *(optional)* — Install `agendum[vectors]` to add semantic similarity via `fastembed` + `sqlite-vec`. Activates automatically alongside FTS5.
- **Entity graph** — Topics and tags form a knowledge graph. Entries sharing 2+ entities are linked automatically. Graph expansion surfaces related knowledge that keyword search misses.

All three signals are fused via Reciprocal Rank Fusion (RRF), then reranked by recency and access frequency. The index rebuilds from Markdown files — no data loss if it gets corrupted.

## Key Capabilities

- **Adaptive context budget** — enrichment scales with task complexity: 4K chars for trivial tasks, up to 10K for large ones
- **Verification gate** — `pm_done(verified=True)` distinguishes tested from untested completions
- **Git auto-extract** — `pm_done` reads `git diff` and `git log` automatically when no files are specified
- **Pluggable enrichment pipeline** — four context sources injected into every work package: project rules (CLAUDE.md/AGENTS.md), memory, dependency context, learnings
- **Dependency resolution** — topological ordering with cycle detection; dependents unblock automatically when upstream tasks complete
- **Memory health** — `pm_status` warns about corrupted entries; `pm_consolidate` strips XML fragments, deduplicates, and flags contradictions
- **Zero config** — auto-initializes on first tool call, derives board name from git remote
- **Git-native storage** — all state is human-readable Markdown + YAML in `.agendum/`, diffable and committable

## Installation

All MCP clients except VS Code use the same config. Add to the appropriate file:

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

| Client | Config location |
|--------|-----------------|
| **Claude Code** | Run: `claude mcp add agendum -- uvx agendum --home serve` |
| **Cursor** | `.cursor/mcp.json` in project root |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **Cline** | Settings › MCP Servers › Edit |
| **Roo Code** | MCP settings file |
| **Claude Desktop** | `claude_desktop_config.json` |

> **VS Code (GitHub Copilot):** Uses `"servers"` instead of `"mcpServers"`. Add to `.vscode/mcp.json`:
> ```json
> {
>   "servers": {
>     "agendum": {
>       "command": "uvx",
>       "args": ["agendum", "--home", "serve"]
>     }
>   }
> }
> ```

### CLI (standalone)

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

## Storage Layout

All state lives in `~/.agendum/` (or `.agendum/` in your project if you prefer local storage):

```
~/.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
```

## Architecture

```
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()
```

## Development

```bash
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
```

## License

MIT
