Skip to content

Session Continuity

Jump to bottom
Pedro Gomes Branquinho edited this page Feb 15, 2026 · 1 revision

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 for full details.

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

Verify Chroma is accessible:

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.

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

3. Skill Files

Copy the skill files to your Claude Code commands directory:

# 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:

## 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:

# 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:

    curl http://localhost:8000/api/v1/heartbeat

  2. Check embedding provider is configured:

    (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:

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

Clone this wiki locally