# In-Memory Kanban

The memory-backed kanban system provides lightweight task tracking stored in Chroma memory. Unlike traditional org-file based kanban, this system is project-scoped, has automatic TTL expiration, and integrates seamlessly with ling workflows.

## Overview

| Aspect | Details |
|--------|---------|
| Storage | Chroma memory (not org files) |
| Scoping | Project-scoped via `directory` parameter |
| TTL | Short-term duration (7 days) |
| Use Case | Session task tracking for agents |

**Data Flow:**
```
Task Create → Chroma Memory → Status Updates → Done (DELETE)
```

## How It Works

Tasks are stored as memory entries with structured metadata:

```clojure
{:type "note"
 :tags ["kanban" "todo" "priority-medium"]
 :content {:task-type "kanban"
           :title "Implement user auth"
           :status "todo"
           :priority "medium"
           :context "Additional notes..."
           :created-at "2026-01-22T10:30:00Z"}}
```

### Storage Details

- **Type:** `note` (enables memory queries)
- **Duration:** `short` (7-day TTL, auto-expires)
- **Tags:** Combination of:
  - `kanban` - identifies as kanban task
  - Status tag: `todo`, `doing`, or `review`
  - Priority tag: `priority-high`, `priority-medium`, or `priority-low`

### Project Scoping

Tasks are scoped to a project via the `directory` parameter. The project ID is derived from the directory path.

**Always pass the `directory` parameter:**
```
mcp_mem_kanban_list_slim(directory: "/home/user/projects/my-project")
```

Without proper scoping:
- Tasks may be invisible to queries
- Cross-project task contamination
- Incorrect kanban stats

## MCP Tools

| Tool | Purpose | Required Params |
|------|---------|-----------------|
| `mcp_mem_kanban_create` | Create task with full options | `title` |
| `mcp_mem_kanban_quick` | Quick add (todo, medium) | `title` |
| `mcp_mem_kanban_list_slim` | List tasks (token-efficient) | - |
| `mcp_mem_kanban_move` | Move task to new status | `task_id`, `new_status` |
| `mcp_mem_kanban_stats` | Get counts by status | - |

### Creating Tasks

**Full control:**
```
mcp__hive__mcp_mem_kanban_create(
  title: "Implement user authentication",
  priority: "high",
  context: "Use JWT tokens, integrate with existing user model",
  directory: "/path/to/project"
)
```

**Quick add (defaults: todo, medium priority):**
```
mcp__hive__mcp_mem_kanban_quick(
  title: "Fix login bug",
  directory: "/path/to/project"
)
```

### Listing Tasks

**List tasks (id, title, status, priority):**
```
mcp__hive__mcp_mem_kanban_list_slim(
  directory: "/path/to/project"
)
```

**Filter by status:**
```
mcp__hive__mcp_mem_kanban_list_slim(
  status: "doing",
  directory: "/path/to/project"
)
```

### Moving Tasks

```
mcp__hive__mcp_mem_kanban_move(
  task_id: "kanban-task-abc123",
  new_status: "doing",
  directory: "/path/to/project"
)
```

### Getting Stats

```
mcp__hive__mcp_mem_kanban_stats(
  directory: "/path/to/project"
)
```

Returns:
```json
{
  "todo": 3,
  "doing": 1,
  "review": 2,
  "total": 6
}
```

## Task Statuses

| Status | Meaning | Behavior |
|--------|---------|----------|
| `todo` | Not started | Default for new tasks |
| `doing` | In progress | Active work |
| `review` | Awaiting review | Pending verification |
| `done` | Completed | **DELETES from memory** |

### Done Deletes Tasks

Moving a task to `done` **permanently removes it from memory**. This is intentional:

- Tasks are ephemeral tracking aids, not permanent records
- Session summaries capture completed work via `/wrap`
- Prevents stale task accumulation
- Memory stays clean and relevant

If you need to preserve completion history, use `/wrap` before marking tasks done.

## Integration with Ling Workflow

### At Session Start

Lings should check for in-progress tasks:

```
# Check what's in progress
mcp__hive__mcp_mem_kanban_list_slim(
  status: "doing",
  directory: "/path/to/project"
)
```

### During Work

Move tasks as you progress:

```
# Start working on a task
mcp__hive__mcp_mem_kanban_move(
  task_id: "task-123",
  new_status: "doing",
  directory: "/path/to/project"
)

# ... do work ...

# Ready for review
mcp__hive__mcp_mem_kanban_move(
  task_id: "task-123",
  new_status: "review",
  directory: "/path/to/project"
)
```

### At Session End

Before `/wrap`, complete tasks:

```
# Mark completed
mcp__hive__mcp_mem_kanban_move(
  task_id: "task-123",
  new_status: "done",
  directory: "/path/to/project"
)

# Then wrap
/wrap
```

Or use `session_complete` to do it all at once:

```
mcp__hive__session_complete(
  commit_msg: "feat: implement user auth",
  task_ids: ["task-123", "task-456"],
  agent_id: "your-CLAUDE_SWARM_SLAVE_ID",
  directory: "/path/to/project"
)
```

### Lifecycle Diagram

```
┌─────────┐    create    ┌──────┐
│  Agent  │─────────────►│ TODO │
└─────────┘              └──┬───┘
                            │ move
                            ▼
                        ┌───────┐
                        │ DOING │◄──────┐
                        └──┬────┘       │
                           │ move       │ (rework)
                           ▼            │
                       ┌────────┐       │
                       │ REVIEW │───────┘
                       └──┬─────┘
                          │ move
                          ▼
                       ┌──────┐
                       │ DONE │──► DELETED from memory
                       └──────┘
```

## Catchup Integration

The `/catchup` skill queries in-memory kanban automatically:

```markdown
### In-Progress Tasks (Kanban)
- **[high]** task-abc: Implement user authentication
- **[medium]** task-def: Fix login bug

### Recommended Starting Point
1. Continue "Implement user authentication" task
```

Stale TODO tasks (> 5 days old) are flagged for attention.

## Comparison with Org-File Kanban

| Feature | Memory Kanban | Org-File Kanban |
|---------|---------------|-----------------|
| Storage | Chroma | `.org` files |
| TTL | 7 days | Permanent |
| Project Scope | Automatic | Manual |
| Tools | `mcp_mem_kanban_*` | `mcp_kanban_*` |
| Best For | Agent sessions | Long-term roadmaps |

Use memory kanban for session-level task tracking. Use org-file kanban for project roadmaps and long-term planning.

## Troubleshooting

### Tasks Not Appearing

**Symptom:** Created tasks don't show in list.

**Checks:**
1. Verify Chroma is running:
   ```bash
   curl http://localhost:8000/api/v1/heartbeat
   ```

2. Check project scope:
   ```
   mcp__hive__mcp_mem_kanban_list_slim(
     directory: "/correct/project/path"
   )
   ```

3. Query raw memory:
   ```
   mcp__hive__mcp_memory_query(
     type: "note",
     tags: ["kanban"],
     directory: "/path/to/project"
   )
   ```

### Task Disappeared After 7 Days

**Symptom:** Older tasks are missing.

**Explanation:** This is expected behavior. Memory kanban uses `short` duration (7-day TTL). Tasks expire automatically.

**Mitigation:**
- Complete or review tasks within the TTL window
- For long-term tracking, use org-file kanban instead
- Important context should be captured in `/wrap` before tasks expire

### Wrong Project Tasks Showing

**Symptom:** Tasks from other projects appear in list.

**Fix:** Always pass the `directory` parameter explicitly:
```
mcp__hive__mcp_mem_kanban_list_slim(
  directory: "/home/user/projects/THIS-project"
)
```

## Related Pages

- [Session-Continuity](Session-Continuity.md) - /wrap and /catchup integration
- [Infrastructure-Setup](Infrastructure-Setup.md) - Chroma setup
- [Troubleshooting](Troubleshooting.md) - General issues