universal-agent-memory 2.9.0 → 3.0.0

package/dist/memory/memory-maintenance.js

@@ -0,0 +1,268 @@
+/**
+ * Automated Memory Maintenance
+ *
+ * Periodic maintenance tasks: verify stale claims, prune decayed entries,
+ * consolidate daily logs, and surface maintenance recommendations.
+ *
+ * Inspired by Total Recall's maintenance cadences and Clawe's heartbeat system.
+ */
+import Database from 'better-sqlite3';
+import { existsSync } from 'fs';
+import { ensureDailyLogSchema } from './daily-log.js';
+const DEFAULT_CONFIG = {
+    staleDaysThreshold: 14,
+    decayRate: 0.95,
+    minImportanceAfterDecay: 1,
+    archiveDaysOld: 30,
+    duplicateSimilarityThreshold: 0.92,
+};
+/**
+ * Run full maintenance cycle on the memory database.
+ */
+export function runMaintenance(dbPath, config = {}) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    const result = {
+        staleEntriesPruned: 0,
+        decayedEntriesUpdated: 0,
+        dailyLogsArchived: 0,
+        duplicatesRemoved: 0,
+        recommendations: [],
+    };
+    if (!existsSync(dbPath)) {
+        result.recommendations.push('Database not found. Run `uam init` first.');
+        return result;
+    }
+    const db = new Database(dbPath);
+    try {
+        // 1. Apply importance decay to old memories
+        result.decayedEntriesUpdated = applyDecay(db, cfg);
+        // 2. Prune entries that decayed below minimum importance
+        result.staleEntriesPruned = pruneStale(db, cfg);
+        // 3. Archive old daily log entries
+        result.dailyLogsArchived = archiveDailyLogs(db, cfg);
+        // 4. Remove duplicates
+        result.duplicatesRemoved = removeDuplicates(db);
+        // 5. Generate recommendations
+        result.recommendations = generateRecommendations(db, cfg);
+    }
+    finally {
+        db.close();
+    }
+    return result;
+}
+function applyDecay(db, cfg) {
+    const now = Date.now();
+    let updated = 0;
+    try {
+        const rows = db.prepare(`
+      SELECT id, importance, timestamp
+      FROM memories
+      WHERE importance > ?
+    `).all(cfg.minImportanceAfterDecay);
+        const updateStmt = db.prepare('UPDATE memories SET importance = ? WHERE id = ?');
+        for (const row of rows) {
+            const daysSince = (now - new Date(row.timestamp).getTime()) / (1000 * 60 * 60 * 24);
+            if (daysSince < 1)
+                continue; // Skip recent entries
+            const decayed = Math.round(row.importance * Math.pow(cfg.decayRate, daysSince));
+            if (decayed !== row.importance && decayed >= cfg.minImportanceAfterDecay) {
+                updateStmt.run(decayed, row.id);
+                updated++;
+            }
+        }
+    }
+    catch {
+        // Table might not exist
+    }
+    try {
+        const rows = db.prepare(`
+      SELECT id, importance, timestamp
+      FROM session_memories
+      WHERE importance > ?
+    `).all(cfg.minImportanceAfterDecay);
+        const updateStmt = db.prepare('UPDATE session_memories SET importance = ? WHERE id = ?');
+        for (const row of rows) {
+            const daysSince = (now - new Date(row.timestamp).getTime()) / (1000 * 60 * 60 * 24);
+            if (daysSince < 1)
+                continue;
+            const decayed = Math.round(row.importance * Math.pow(cfg.decayRate, daysSince));
+            if (decayed !== row.importance && decayed >= cfg.minImportanceAfterDecay) {
+                updateStmt.run(decayed, row.id);
+                updated++;
+            }
+        }
+    }
+    catch {
+        // Table might not exist
+    }
+    return updated;
+}
+function pruneStale(db, cfg) {
+    let pruned = 0;
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - cfg.staleDaysThreshold);
+    const cutoff = cutoffDate.toISOString();
+    try {
+        const result = db.prepare(`
+      DELETE FROM memories
+      WHERE importance <= ? AND timestamp < ?
+    `).run(cfg.minImportanceAfterDecay, cutoff);
+        pruned += result.changes;
+    }
+    catch {
+        // Table might not exist
+    }
+    try {
+        const result = db.prepare(`
+      DELETE FROM session_memories
+      WHERE importance <= ? AND timestamp < ?
+    `).run(cfg.minImportanceAfterDecay, cutoff);
+        pruned += result.changes;
+    }
+    catch {
+        // Table might not exist
+    }
+    return pruned;
+}
+function archiveDailyLogs(db, cfg) {
+    try {
+        ensureDailyLogSchema(db);
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - cfg.archiveDaysOld);
+        const cutoffDate = cutoff.toISOString().split('T')[0];
+        // Delete promoted entries older than threshold
+        const result = db.prepare(`
+      DELETE FROM daily_log WHERE date < ? AND promoted = 1
+    `).run(cutoffDate);
+        return result.changes;
+    }
+    catch {
+        return 0;
+    }
+}
+function removeDuplicates(db) {
+    let removed = 0;
+    try {
+        // Remove exact duplicates in memories (keep lowest id)
+        const result = db.prepare(`
+      DELETE FROM memories
+      WHERE id NOT IN (
+        SELECT MIN(id) FROM memories GROUP BY content, project_id
+      )
+    `).run();
+        removed += result.changes;
+    }
+    catch {
+        // Table might not exist
+    }
+    try {
+        // Remove exact duplicates in session_memories
+        const result = db.prepare(`
+      DELETE FROM session_memories
+      WHERE id NOT IN (
+        SELECT MIN(id) FROM session_memories GROUP BY content, session_id
+      )
+    `).run();
+        removed += result.changes;
+    }
+    catch {
+        // Table might not exist
+    }
+    return removed;
+}
+function generateRecommendations(db, cfg) {
+    const recs = [];
+    try {
+        // Check total memory count
+        const memCount = db.prepare('SELECT COUNT(*) as c FROM memories').get().c;
+        if (memCount > 45) {
+            recs.push(`Working memory near capacity (${memCount}/50). Consider promoting important entries and pruning old ones.`);
+        }
+        // Check for stale entries
+        const staleDate = new Date();
+        staleDate.setDate(staleDate.getDate() - cfg.staleDaysThreshold);
+        const staleCount = db.prepare(`
+      SELECT COUNT(*) as c FROM memories WHERE timestamp < ? AND importance <= 3
+    `).get(staleDate.toISOString()).c;
+        if (staleCount > 0) {
+            recs.push(`${staleCount} stale entries with low importance found. Run maintenance again or review manually.`);
+        }
+    }
+    catch {
+        // Table might not exist
+    }
+    try {
+        // Check unpromoted daily log entries
+        ensureDailyLogSchema(db);
+        const unpromoted = db.prepare(`
+      SELECT COUNT(*) as c FROM daily_log WHERE promoted = 0
+    `).get().c;
+        if (unpromoted > 10) {
+            recs.push(`${unpromoted} unpromoted daily log entries. Run \`uam memory promote\` to review.`);
+        }
+    }
+    catch {
+        // Table might not exist
+    }
+    try {
+        // Check for entries with very low importance
+        const lowImp = db.prepare(`
+      SELECT COUNT(*) as c FROM session_memories WHERE importance <= 2
+    `).get().c;
+        if (lowImp > 20) {
+            recs.push(`${lowImp} session memories with very low importance. These may be pruned on next maintenance.`);
+        }
+    }
+    catch {
+        // Table might not exist
+    }
+    if (recs.length === 0) {
+        recs.push('Memory system is healthy. No action needed.');
+    }
+    return recs;
+}
+/**
+ * Get a quick health summary without running full maintenance.
+ */
+export function getHealthSummary(dbPath) {
+    const summary = {
+        memoriesCount: 0,
+        sessionCount: 0,
+        dailyLogCount: 0,
+        staleCount: 0,
+        unpromotedCount: 0,
+        healthy: true,
+    };
+    if (!existsSync(dbPath))
+        return summary;
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        try {
+            summary.memoriesCount = db.prepare('SELECT COUNT(*) as c FROM memories').get().c;
+        }
+        catch { /* table doesn't exist */ }
+        try {
+            summary.sessionCount = db.prepare('SELECT COUNT(*) as c FROM session_memories').get().c;
+        }
+        catch { /* table doesn't exist */ }
+        try {
+            summary.dailyLogCount = db.prepare('SELECT COUNT(*) as c FROM daily_log').get().c;
+            summary.unpromotedCount = db.prepare('SELECT COUNT(*) as c FROM daily_log WHERE promoted = 0').get().c;
+        }
+        catch { /* table doesn't exist */ }
+        const staleDate = new Date();
+        staleDate.setDate(staleDate.getDate() - 14);
+        try {
+            summary.staleCount = db.prepare(`
+        SELECT COUNT(*) as c FROM memories WHERE timestamp < ? AND importance <= 3
+      `).get(staleDate.toISOString()).c;
+        }
+        catch { /* table doesn't exist */ }
+        summary.healthy = summary.memoriesCount <= 45 && summary.staleCount < 10 && summary.unpromotedCount < 20;
+    }
+    finally {
+        db.close();
+    }
+    return summary;
+}
+//# sourceMappingURL=memory-maintenance.js.map

package/dist/memory/memory-maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-maintenance.js","sourceRoot":"","sources":["../../src/memory/memory-maintenance.ts"],"names":[],"mappings":"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"}

package/dist/memory/write-gate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Write Gate for UAM Memory System
+ *
+ * Evaluates candidate memories against 5 criteria before persisting.
+ * Inspired by Total Recall's write gate: "Does this change future behavior?"
+ *
+ * Gate Criteria:
+ * 1. Behavioral change - changes how the agent operates in future
+ * 2. Commitment with consequences - deadline, deliverable, follow-up
+ * 3. Decision with rationale - why X was chosen over Y
+ * 4. Stable recurring fact - not transient, will matter again
+ * 5. Explicit user request - user said "remember this"
+ */
+export interface WriteGateResult {
+    passed: boolean;
+    score: number;
+    criteria: GateCriteria[];
+    rejectionReason?: string;
+}
+export interface GateCriteria {
+    name: string;
+    matched: boolean;
+    confidence: number;
+    evidence?: string;
+}
+export interface WriteGateConfig {
+    minScore: number;
+    enableFuzzyMatching: boolean;
+}
+/**
+ * Evaluate whether a candidate memory should be persisted.
+ * Returns a WriteGateResult with score and matched criteria.
+ */
+export declare function evaluateWriteGate(content: string, config?: WriteGateConfig): WriteGateResult;
+/**
+ * Format a human-readable summary of the write gate evaluation.
+ */
+export declare function formatGateResult(result: WriteGateResult): string;
+//# sourceMappingURL=write-gate.d.ts.map

package/dist/memory/write-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-gate.d.ts","sourceRoot":"","sources":["../../src/memory/write-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AA0DD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,eAAgC,GACvC,eAAe,CAqGjB;AAkBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBhE"}

package/dist/memory/write-gate.js

@@ -0,0 +1,190 @@
+/**
+ * Write Gate for UAM Memory System
+ *
+ * Evaluates candidate memories against 5 criteria before persisting.
+ * Inspired by Total Recall's write gate: "Does this change future behavior?"
+ *
+ * Gate Criteria:
+ * 1. Behavioral change - changes how the agent operates in future
+ * 2. Commitment with consequences - deadline, deliverable, follow-up
+ * 3. Decision with rationale - why X was chosen over Y
+ * 4. Stable recurring fact - not transient, will matter again
+ * 5. Explicit user request - user said "remember this"
+ */
+const DEFAULT_CONFIG = {
+    minScore: 0.3,
+    enableFuzzyMatching: true,
+};
+const BEHAVIORAL_PATTERNS = [
+    /\b(prefer|always|never|don'?t|avoid|stop|instead)\b/i,
+    /\b(use|switch to|migrate to|adopt)\b.*\b(over|instead of|not)\b/i,
+    /\b(default|convention|standard|rule|policy)\b/i,
+    /\b(format|style|indent|naming|casing)\b/i,
+    /\b(timezone|locale|language|encoding)\b/i,
+    /\b(before|after|when|every time)\b.*\b(always|must|should)\b/i,
+];
+const COMMITMENT_PATTERNS = [
+    /\b(deadline|due|by|until|before)\b.*\b(\d{4}|\d{1,2}[\/\-]\d{1,2}|monday|tuesday|wednesday|thursday|friday|saturday|sunday|tomorrow|next week|end of)\b/i,
+    /\b(deliver|ship|release|deploy|submit|send)\b.*\b(by|before|on)\b/i,
+    /\b(follow up|check back|revisit|circle back|get back)\b/i,
+    /\b(waiting on|blocked by|depends on|need from)\b/i,
+    /\b(committed to|promised|agreed to|will do)\b/i,
+    /\b(TODO|FIXME|HACK)\b/,
+];
+const DECISION_PATTERNS = [
+    /\b(decided|chose|picked|selected|went with|opted for)\b/i,
+    /\b(because|reason|rationale|trade-?off|pros? and cons?)\b/i,
+    /\b(over|instead of|rather than|as opposed to)\b/i,
+    /\b(alternative|option|approach|strategy|architecture)\b/i,
+    /\b(evaluated|compared|benchmarked|tested)\b.*\b(and|vs\.?|versus)\b/i,
+];
+const STABLE_FACT_PATTERNS = [
+    /\b(api|endpoint|url|port|host|domain)\b.*\b(is|at|on)\b/i,
+    /\b(version|release|v\d+)\b/i,
+    /\b(password|secret|key|token|credential)\b.*\b(stored|located|in|at)\b/i,
+    /\b(schema|table|column|field|index)\b.*\b(is|has|named)\b/i,
+    /\b(environment|staging|production|dev)\b.*\b(uses?|runs?|on|at)\b/i,
+    /\b(rotates?|expires?|renews?)\b.*\b(every|monthly|weekly|daily)\b/i,
+    /\b(contact|email|phone|slack)\b.*\b(is|at)\b/i,
+];
+const EXPLICIT_REMEMBER_PATTERNS = [
+    /\b(remember|memorize|note|save|store|record|keep in mind)\b.*\b(this|that)\b/i,
+    /\b(important|critical|crucial|key|essential)\b.*\b(to (know|note|remember))\b/i,
+    /\b(don'?t forget|make sure to remember|for future reference)\b/i,
+    /\bremember\s*:/i,
+];
+const NOISE_PATTERNS = [
+    /^(thanks|thank you|ok|okay|got it|sounds good|great|perfect|nice|cool|lgtm)/i,
+    /^(yes|no|sure|right|correct|exactly|indeed|absolutely)$/i,
+    /\b(looks? good|works? for me|makes? sense)\b/i,
+    /^(can you|could you|please|would you)\b/i,
+    /\b(just ran|just tested|just checked|running now)\b/i,
+];
+/**
+ * Evaluate whether a candidate memory should be persisted.
+ * Returns a WriteGateResult with score and matched criteria.
+ */
+export function evaluateWriteGate(content, config = DEFAULT_CONFIG) {
+    if (!content || content.trim().length === 0) {
+        return {
+            passed: false,
+            score: 0,
+            criteria: [],
+            rejectionReason: 'Empty content',
+        };
+    }
+    const trimmed = content.trim();
+    // Short content is likely noise
+    if (trimmed.length < 10) {
+        return {
+            passed: false,
+            score: 0,
+            criteria: [],
+            rejectionReason: 'Content too short to be a meaningful memory',
+        };
+    }
+    // Check for noise patterns first
+    for (const pattern of NOISE_PATTERNS) {
+        if (pattern.test(trimmed)) {
+            return {
+                passed: false,
+                score: 0,
+                criteria: [],
+                rejectionReason: 'Content matches noise pattern (acknowledgment, transient request)',
+            };
+        }
+    }
+    const criteria = [];
+    // Criterion 1: Behavioral change
+    const behavioralScore = matchPatterns(trimmed, BEHAVIORAL_PATTERNS);
+    criteria.push({
+        name: 'behavioral_change',
+        matched: behavioralScore > 0,
+        confidence: behavioralScore,
+        evidence: behavioralScore > 0 ? 'Changes how the agent should operate' : undefined,
+    });
+    // Criterion 2: Commitment with consequences
+    const commitmentScore = matchPatterns(trimmed, COMMITMENT_PATTERNS);
+    criteria.push({
+        name: 'commitment',
+        matched: commitmentScore > 0,
+        confidence: commitmentScore,
+        evidence: commitmentScore > 0 ? 'Contains deadline, deliverable, or follow-up' : undefined,
+    });
+    // Criterion 3: Decision with rationale
+    const decisionScore = matchPatterns(trimmed, DECISION_PATTERNS);
+    criteria.push({
+        name: 'decision_rationale',
+        matched: decisionScore > 0,
+        confidence: decisionScore,
+        evidence: decisionScore > 0 ? 'Records a decision and its reasoning' : undefined,
+    });
+    // Criterion 4: Stable recurring fact
+    const factScore = matchPatterns(trimmed, STABLE_FACT_PATTERNS);
+    criteria.push({
+        name: 'stable_fact',
+        matched: factScore > 0,
+        confidence: factScore,
+        evidence: factScore > 0 ? 'Durable fact that will be referenced again' : undefined,
+    });
+    // Criterion 5: Explicit user request
+    const explicitScore = matchPatterns(trimmed, EXPLICIT_REMEMBER_PATTERNS);
+    criteria.push({
+        name: 'explicit_request',
+        matched: explicitScore > 0,
+        confidence: explicitScore,
+        evidence: explicitScore > 0 ? 'User explicitly requested to remember' : undefined,
+    });
+    // Aggregate score: highest matching criterion wins, with bonus for multiple matches
+    const matchedCriteria = criteria.filter(c => c.matched);
+    const maxConfidence = Math.max(...criteria.map(c => c.confidence), 0);
+    const multiMatchBonus = matchedCriteria.length > 1 ? 0.1 * (matchedCriteria.length - 1) : 0;
+    const score = Math.min(1.0, maxConfidence + multiMatchBonus);
+    // High importance heuristic: long, structured content with technical terms
+    const lengthBonus = trimmed.length > 200 ? 0.15 : trimmed.length > 100 ? 0.05 : 0;
+    const finalScore = Math.min(1.0, score + lengthBonus);
+    const passed = finalScore >= config.minScore;
+    return {
+        passed,
+        score: finalScore,
+        criteria,
+        rejectionReason: passed
+            ? undefined
+            : 'Content does not match any write gate criteria (behavioral change, commitment, decision, stable fact, or explicit request)',
+    };
+}
+/**
+ * Match content against a set of regex patterns.
+ * Returns a confidence score 0-1 based on number and quality of matches.
+ */
+function matchPatterns(content, patterns) {
+    let matches = 0;
+    for (const pattern of patterns) {
+        if (pattern.test(content)) {
+            matches++;
+        }
+    }
+    if (matches === 0)
+        return 0;
+    // Score: 0.4 for first match, +0.15 for each additional, cap at 1.0
+    return Math.min(1.0, 0.4 + (matches - 1) * 0.15);
+}
+/**
+ * Format a human-readable summary of the write gate evaluation.
+ */
+export function formatGateResult(result) {
+    const status = result.passed ? 'PASSED' : 'REJECTED';
+    const lines = [`Write Gate: ${status} (score: ${result.score.toFixed(2)})`];
+    for (const criterion of result.criteria) {
+        const icon = criterion.matched ? '+' : '-';
+        lines.push(`  ${icon} ${criterion.name}: ${criterion.matched ? `yes (${criterion.confidence.toFixed(2)})` : 'no'}`);
+        if (criterion.evidence) {
+            lines.push(`    ${criterion.evidence}`);
+        }
+    }
+    if (result.rejectionReason) {
+        lines.push(`  Reason: ${result.rejectionReason}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=write-gate.js.map

package/dist/memory/write-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-gate.js","sourceRoot":"","sources":["../../src/memory/write-gate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-agent-memory",
-  "version": "2.9.0",
+  "version": "3.0.0",
   "description": "Universal AI agent memory system - CLAUDE.md templates, memory, worktrees for Claude Code, Factory.AI, VSCode, OpenCode",
   "type": "module",
   "main": "dist/index.js",

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,20 @@
+#!/usr/bin/env bash
+# UAM Pre-Compact Hook for Claude Code
+# Writes a timestamp marker to the daily log before context compaction.
+# Fails safely - never blocks the agent.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.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

package/templates/hooks/session-start.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# UAM Session Start Hook for Claude Code
+# Injects open loops and recent daily context at session start.
+# Fails safely - never blocks the agent.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
+
+if [ ! -f "$DB_PATH" ]; then
+  exit 0
+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