# Session Continuity

Session continuity enables Claude agents to maintain context across sessions. The `/wrap` skill saves session state at the end, and `/catchup` restores it at the start of the next session.

## Overview

| Skill | Purpose | When to Use |
|-------|---------|-------------|
| `/wrap` | Crystallize session data into memory | End of session |
| `/catchup` | Restore context from memory | Start of session |

**Data Flow:**
```
Session 1 → /wrap → Chroma Memory → /catchup → Session 2
```

## Prerequisites

### 1. Chroma Memory System

The memory system must be running. See [Infrastructure-Setup](Infrastructure-Setup.md) for full details.

```bash
# Start Chroma with docker-compose
cd /path/to/hive-mcp
docker-compose up -d chroma
```

Verify Chroma is accessible:
```bash
curl http://localhost:8000/api/v1/heartbeat
# Expected: {"nanosecond heartbeat":...}
```

### 2. Emacs Configuration

Ensure hive-mcp.el is loaded with builtin workflows enabled. See [Emacs-Configuration](Emacs-Configuration.md).

```elisp
;; In your Emacs config
(setq hive-mcp-load-builtin-workflows t)
```

### 3. Skill Files

Copy the skill files to your Claude Code commands directory:

```bash
# Create the commands directory if it doesn't exist
mkdir -p ~/.claude/commands

# Copy skill files
cp /path/to/hive-mcp/.claude/commands/catchup.md ~/.claude/commands/
cp /path/to/hive-mcp/.claude/commands/wrap.md ~/.claude/commands/
```

## Usage

### Starting a Session with `/catchup`

At the beginning of a new session, run:

```
/catchup
```

This retrieves:
- **Session summaries** - Previous session notes tagged `session-summary`
- **Active decisions** - Architecture and design decisions
- **Code conventions** - Project-specific patterns
- **Priority conventions** - Swarm patterns tagged `catchup-priority` (loaded with full content)
- **Git state** - Current branch, uncommitted changes, recent commits
- **Kanban status** - In-progress and TODO tasks
- **Expiring entries** - Memory entries expiring within 7 days

**Example output:**
```markdown
## Session Catch-Up

### Current State
- Active branch: `feature/new-api`
- Uncommitted changes: yes
- Last commit: `abc1234 - Add user authentication`

### Memory Context
**Recent Sessions:**
- [2026-01-21]: Implemented user login flow

**Active Decisions:**
- Use JWT for session tokens
- Cache user data in Redis

### In-Progress Tasks (Kanban)
- Task 1: Complete API documentation

### Recommended Starting Point
1. Review uncommitted changes
2. Continue API documentation task
```

### Ending a Session with `/wrap`

At the end of a session, run:

```
/wrap
```

This crystallizes:
- **Session summary** - Auto-generated from completed tasks and commits
- **Progress notes** - Converted from kanban completions
- **Git commits** - Commits made during the session

**For lings (swarm agents):** Pass your agent ID for proper attribution:

```
mcp__hive__wrap_crystallize(
  agent_id: "your-CLAUDE_SWARM_SLAVE_ID",
  directory: "/path/to/your/project"
)
```

**For coordinators:**
```
mcp__hive__wrap_crystallize(
  directory: "/path/to/your/project"
)
```

## Workflow Details

### What `/catchup` Does Step-by-Step

1. **Query Chroma memory** for project-scoped entries:
   - Notes with `session-summary` tag (limit 3)
   - Decisions (limit 10)
   - Conventions (limit 10, priority ones first)
   - Snippets (limit 5)

2. **Check file context:**
   - Read `.claude/SESSION_CONTEXT.json` if exists
   - Read project `CLAUDE.md` if exists

3. **Load kanban status:**
   - In-memory kanban tasks (DOING status)
   - Check for stale TODO tasks (> 5 days)

4. **Gather git state:**
   - Current branch
   - Uncommitted changes
   - Recent commit history

5. **Check memory health:**
   - Entries expiring within 7 days
   - Prompt user to promote/demote as needed

6. **Present summary** and ask for direction

### What `/wrap` Does Step-by-Step

1. **Harvest session data:**
   - Recent notes from recall buffer
   - Git commits since session start
   - Completed kanban tasks

2. **Generate session summary:**
   - Aggregate completed tasks
   - Include commit summaries
   - Tag with `session-summary` and `wrap-generated`

3. **Promote qualifying entries:**
   - Calculate promotion scores based on recall patterns
   - Promote entries that exceed threshold

4. **Emit wrap_notify event:**
   - For hivemind coordination
   - Enables crystal permeation across agents

5. **Flush recall buffer:**
   - Clear temporary recall tracking

### Memory Duration Hierarchy

| Duration | TTL | Use Case |
|----------|-----|----------|
| `ephemeral` | 1 day | Temporary context, auto-expires |
| `short` | 7 days | Active work context |
| `medium` | 30 days | Project milestones |
| `long` | 90 days | Project-wide knowledge |
| `permanent` | Never | Critical decisions, conventions |

Session summaries are stored with `short` duration (7 days) by default.

## Project Scoping

**Always pass the `directory` parameter** to ensure operations target the correct project.

```
# Get your working directory
pwd

# Pass to MCP tools
mcp__hive__wrap_crystallize(directory: "/home/user/projects/my-project")
mcp__hive__mcp_memory_query(type: "note", directory: "/home/user/projects/my-project")
```

Without proper scoping:
- Wraps may be tagged with wrong project
- Catchup may load data from other projects
- Cross-project memory contamination

## Multi-Agent (Swarm) Usage

### Ling Sessions

Lings must pass their agent ID explicitly:

```bash
# Get your agent ID
echo $CLAUDE_SWARM_SLAVE_ID

# Pass to wrap_crystallize
mcp__hive__wrap_crystallize(
  agent_id: "swarm-fix-bug-1768840244",
  directory: "/path/to/project"
)
```

**Why explicit agent_id?** The MCP server runs in the coordinator's JVM, so `System.getenv("CLAUDE_SWARM_SLAVE_ID")` returns the coordinator's ID, not the ling's.

### Coordinator Permeation

Coordinators can process ling wrap data:

```
mcp__hive__mcp_permeate_crystals(
  directory: "/path/to/project",
  include_children: true
)
```

| Parameter | Default | Description |
|-----------|---------|-------------|
| `directory` | - | Project scope for filtering wraps |
| `include_children` | `true` | Include child project wraps (e.g., `myproject:submodule`) |

### Full Session Lifecycle (session_complete)

For lings that want to commit, complete tasks, and wrap in one call:

```
mcp__hive__session_complete(
  commit_msg: "feat: implement user authentication",
  task_ids: ["kanban-task-1", "kanban-task-2"],
  agent_id: "swarm-auth-feature-123456",
  directory: "/path/to/project"
)
```

## Troubleshooting

### Memory Not Storing

**Symptom:** `/wrap` runs but `/catchup` shows no data.

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

2. Check embedding provider is configured:
   ```elisp
   (hive-mcp-chroma-embedding-configured-p)
   ```

3. Verify project scope:
   ```
   mcp__hive__mcp_memory_query(type: "note", scope: "all", limit: 10)
   ```

### Missing Skill Files

**Symptom:** `/catchup` or `/wrap` command not recognized.

**Fix:** Copy skill files to your commands directory:
```bash
mkdir -p ~/.claude/commands
cp /path/to/hive-mcp/.claude/commands/catchup.md ~/.claude/commands/
cp /path/to/hive-mcp/.claude/commands/wrap.md ~/.claude/commands/
```

### Wrong Project Context

**Symptom:** Catchup loads data from a different project.

**Fix:** Always pass the `directory` parameter:
```
/catchup
# When prompted or in skill, ensure directory is your pwd
```

### Ling Attribution Shows "coordinator"

**Symptom:** Wrap notifications show `coordinator` instead of ling ID.

**Fix:** Pass `agent_id` explicitly to `wrap_crystallize`:
```
mcp__hive__wrap_crystallize(
  agent_id: "<your CLAUDE_SWARM_SLAVE_ID>",
  directory: "<your pwd>"
)
```

### Expiring Entries Warning

**Symptom:** Catchup shows many entries expiring soon.

**Actions:**
- **Promote important entries:**
  ```
  mcp__hive__mcp_memory_promote(id: "entry-id")
  ```
- **Let irrelevant entries expire** - no action needed
- **Demote outdated entries:**
  ```
  mcp__hive__mcp_memory_demote(id: "entry-id")
  ```

## Related Pages

- [Installation](Installation.md) - Initial setup
- [Infrastructure-Setup](Infrastructure-Setup.md) - Chroma and dependencies
- [Emacs-Configuration](Emacs-Configuration.md) - Emacs-side setup
- [Troubleshooting](Troubleshooting.md) - General troubleshooting