universal-agent-memory 2.9.0 → 3.0.1

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/SCHEMA.md

@@ -0,0 +1,57 @@
+# UAM Memory Schema
+
+> Loaded every session alongside working memory. Teaches the agent how the memory system works.
+
+## Memory Tiers
+
+| Tier | Storage | Latency | Loaded |
+|------|---------|---------|--------|
+| L1 Working | SQLite `memories` | <1ms | Always (last 50) |
+| L2 Session | SQLite `session_memories` | <5ms | Current session |
+| L3 Semantic | Qdrant vectors | ~50ms | On-demand search |
+| L4 Graph | SQLite `entities`/`relationships` | <20ms | On-demand |
+| Daily Log | SQLite `daily_log` | <1ms | Today + yesterday |
+
+## Write Rules
+
+**Write Gate**: Before storing anything, it must pass at least one criterion:
+1. Changes future behavior (preference, boundary, recurring pattern)
+2. Commitment with consequences (deadline, deliverable, follow-up)
+3. Decision with rationale (why X over Y)
+4. Stable recurring fact (not transient, will matter again)
+5. Explicit "remember this" request
+
+**Default destination**: Daily log first. Promote to permanent memory later.
+
+**Never**: silently overwrite. Mark old entries `[superseded]` with date and reason.
+
+## Read Rules
+
+- Working memory and this schema are always loaded
+- Daily log checked for today and yesterday
+- Registers/semantic memory searched on demand when topic is relevant
+- Use `uam memory query` for anything older
+
+## When to Write
+
+| Trigger | Destination |
+|---------|-------------|
+| User says "remember" | Daily log + maybe working memory |
+| User corrects you | Supersede old + write corrected across all tiers |
+| Decision with rationale | Daily log, promote if durable |
+| Preference expressed | Daily log, promote to working memory |
+| Commitment/deadline | Daily log + working memory |
+| Debugging details | **DISCARD** |
+| Transient state | **DISCARD** |
+| Acknowledgments | **DISCARD** |
+
+## Correction Protocol
+
+When corrected: (1) find original, (2) mark superseded with reason, (3) write corrected version to daily log + working memory + semantic memory, (4) verify next session.
+
+## Maintenance
+
+- Memories decay: `effective_importance = importance * (0.95 ^ days_since_access)`
+- Consolidation triggers every 10 new entries
+- Stale entries (>14 days unaccessed) auto-demote from hot to warm tier
+- Run `uam memory maintain` periodically for health checks

package/templates/hooks/pre-compact.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# UAM Pre-Compact Hook for Claude Code
+# 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
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Record a compaction marker in memory so sessions can detect context resets
+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

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# UAM Session Start Hook for Claude Code
+# 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)
+recent=$(sqlite3 "$DB_PATH" "
+  SELECT type, content FROM memories
+  WHERE timestamp >= datetime('now', '-1 day')
+  ORDER BY id DESC
+  LIMIT 10;
+" 2>/dev/null || true)
+
+if [ -n "$recent" ]; then
+  output+="## Recent Memory Context"$'\n'
+  output+="$recent"$'\n\n'
+fi
+
+# Open loops from session memories
+open_loops=$(sqlite3 "$DB_PATH" "
+  SELECT content FROM session_memories
+  WHERE type IN ('action','goal','decision')
+    AND importance >= 7
+  ORDER BY id DESC
+  LIMIT 5;
+" 2>/dev/null || true)
+
+if [ -n "$open_loops" ]; then
+  output+="## Open Loops"$'\n'
+  output+="$open_loops"$'\n'
+fi
+
+if [ -n "$output" ]; then
+  echo "$output"
+fi