universal-agent-memory 3.0.0 → 3.1.0

package/templates/CLAUDE.template.md

@@ -740,9 +740,11 @@ uam agent status                                  # Check other active agents
 
 ## MULTI-AGENT COORDINATION PROTOCOL
 
-**Parallel-first rule**: When safe, run independent tool calls in parallel (searches, reads, status checks) and invoke multiple subagents concurrently for review. Optimize for fewer turns and lower tokens without losing accuracy.
+**Skip this section for single-agent sessions.** Only activate when multiple agents work concurrently (e.g., parallel subagents via Task tool, or multiple Claude Code sessions on same repo).
 
-### Before Claiming Any Work
+**Parallel-first rule**: When safe, run independent tool calls in parallel (searches, reads, status checks) and invoke multiple subagents concurrently for review.
+
+### Before Claiming Any Work (multi-agent only)
 
 ```bash
 uam agent overlaps --resource "<files-or-directories>"
@@ -750,13 +752,12 @@ uam agent overlaps --resource "<files-or-directories>"
 
 ### Overlap Response Matrix
 
-| Risk Level | Action | Rationale |
-|------------|--------|-----------|
-| `none` | Proceed immediately | No conflict possible |
-| `low` | Proceed, note merge order | Different files/sections |
-| `medium` | Announce, coordinate sections | Same directory |
-| `high` | Wait or split work | Same file, different sections |
-| `critical` | STOP - request handoff | Same file, same sections |
+| Risk Level | Action |
+|------------|--------|
+| `none` | Proceed immediately |
+| `low` | Proceed, note merge order |
+| `medium` | Announce, coordinate sections |
+| `high`/`critical` | Wait or split work |
 
 ### Agent Capability Routing
 
@@ -786,21 +787,11 @@ uam agent overlaps --resource "<files-or-directories>"
 
 ## MULTI-AGENT EXECUTION (DEPENDENCY-AWARE)
 
-**Goal**: Finish faster by parallelizing independent work while preserving correctness and avoiding conflicts.
-
-**Aggressive parallelization mandate**: Default to multi-agent execution whenever tasks can be safely decomposed; only stay single-threaded when dependencies or overlap risk make parallel work unsafe.
-
-**Process**:
-1. **Decompose** the request into discrete work items with clear inputs/outputs.
-2. **Map dependencies** (A blocks B). Only run B after A is complete.
-3. **Parallelize** dependency-free items with separate agents and explicit file boundaries.
-4. **Gate edits** with `uam agent overlaps --resource "<files>"` before touching any file.
-5. **Merge in dependency order** (upstream first). Rebase or re-run dependent steps if needed.
-
-**Conflict avoidance**:
-- One agent per file at a time
-- Declare file ownership in prompts
-- If overlap risk is high, wait or split by section
+**Skip for single-agent sessions.** When using parallel subagents:
+1. **Decompose** into discrete work items. **Map dependencies** (A blocks B).
+2. **Parallelize** dependency-free items with separate agents and explicit file boundaries.
+3. **Gate edits** with `uam agent overlaps --resource "<files>"` before touching any file.
+4. **Merge in dependency order** (upstream first).
 
 ---
 
@@ -882,13 +873,19 @@ effective_importance = importance * (0.95 ^ days_since_access)
 
 ## WORKTREE WORKFLOW
 
-**ALL code changes use worktrees. NO EXCEPTIONS.**
+**Use worktrees for multi-file features/refactors. Skip for single-file fixes.**
+
+| Change Scope | Workflow |
+|-------------|----------|
+| Single-file fix (<20 lines) | Direct commit to feature branch, no worktree needed |
+| Multi-file change (2-5 files) | Worktree recommended if touching shared interfaces |
+| Feature/refactor (3+ files, new feature) | Worktree required |
+| CLAUDE.md or config changes | Worktree required |
 
 ```bash
-# Create
+# Create (when needed)
 {{WORKTREE_CREATE_CMD}} <slug>
 cd {{WORKTREE_DIR}}/NNN-<slug>/
-pwd | grep -q "{{WORKTREE_DIR}}" || echo "STOP!"  # Verify location
 
 # Work
 git add -A && git commit -m "type: description"
@@ -896,7 +893,7 @@ git add -A && git commit -m "type: description"
 # PR (runs tests, triggers parallel reviewers)
 {{WORKTREE_PR_CMD}} <id>
 
-# Cleanup
+# Cleanup (ALWAYS cleanup after merge)
 {{WORKTREE_CLEANUP_CMD}} <id>
 ```
 
@@ -934,10 +931,13 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 | work request (fix/add/change/update/create/implement/build) | `uam task create --type task` |
 | bug report/error | `uam task create --type bug` |
 | feature request | `uam task create --type feature` |
-| code file for editing | check overlaps -> skills -> worktree |
+| single-file fix | direct commit to branch, skip worktree |
+| multi-file feature (3+ files) | create worktree, then work |
 | review/check/look | query memory first |
 | ANY code change | tests required |
 
+**Agent coordination**: Only use `uam agent` commands when multiple agents are active concurrently. For single-agent sessions (most common), skip agent registration and overlap checks.
+
 ---
 
 ## UAM VISUAL STATUS FEEDBACK (MANDATORY WHEN UAM IS ACTIVE)

package/templates/hooks/pre-compact.sh

@@ -1,11 +1,13 @@
 #!/usr/bin/env bash
 # UAM Pre-Compact Hook for Claude Code
-# Writes a timestamp marker to the daily log before context compaction.
+# 1. Writes a timestamp marker to the daily log before context compaction
+# 2. Marks any agents registered by this session as completed
 # Fails safely - never blocks the agent.
 set -euo pipefail
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
+COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
 
 if [ ! -f "$DB_PATH" ]; then
   exit 0
@@ -18,3 +20,21 @@ sqlite3 "$DB_PATH" "
   INSERT OR IGNORE INTO memories (timestamp, type, content)
   VALUES ('$TIMESTAMP', 'action', '[pre-compact] Context compaction at $TIMESTAMP');
 " 2>/dev/null || true
+
+# Clean up agents with recent heartbeats (likely from this session being compacted)
+# Mark as completed, release their claims
+if [ -f "$COORD_DB" ]; then
+  sqlite3 "$COORD_DB" "
+    DELETE FROM work_claims WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes')
+    );
+    UPDATE work_announcements SET completed_at='$TIMESTAMP'
+      WHERE completed_at IS NULL AND agent_id IN (
+        SELECT id FROM agent_registry
+        WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes')
+      );
+    UPDATE agent_registry SET status='completed'
+      WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes');
+  " 2>/dev/null || true
+fi

package/templates/hooks/session-start.sh

@@ -1,16 +1,37 @@
 #!/usr/bin/env bash
 # UAM Session Start Hook for Claude Code
-# Injects open loops and recent daily context at session start.
+# 1. Cleans stale agents (heartbeat >24h old)
+# 2. Injects open loops and recent daily context
 # Fails safely - never blocks the agent.
 set -euo pipefail
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
+COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
 
 if [ ! -f "$DB_PATH" ]; then
   exit 0
 fi
 
+# Clean stale agents from coordination DB (heartbeat >24h old)
+if [ -f "$COORD_DB" ]; then
+  sqlite3 "$COORD_DB" "
+    DELETE FROM work_claims WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours')
+    );
+    DELETE FROM work_announcements WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours')
+    ) AND completed_at IS NULL;
+    UPDATE agent_registry SET status='failed'
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours');
+    DELETE FROM agent_registry
+      WHERE status IN ('completed','failed') AND started_at < datetime('now','-7 days');
+    DELETE FROM agent_messages WHERE created_at < datetime('now','-24 hours');
+  " 2>/dev/null || true
+fi
+
 output=""
 
 # Recent memories (last 24h, high importance)