mega-brain-ai 1.3.0

package/.claude/hooks/agent_memory_persister.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+Agent Memory Persister Hook v1.0 (Mega Brain)
+
+Persists session learnings to the active agent's memory file at session end.
+Adapted from: aios-core/.claude/hooks/agent_memory_persister.py
+
+LIFECYCLE:
+  READ:  skill_router.py (UserPromptSubmit) -> loads .claude/agent-memory/{slug}/MEMORY.md
+  WRITE: post_batch_cascading.py (PostToolUse) -> writes batch learnings
+  WRITE: THIS HOOK (SessionEnd) -> writes session summary
+
+BEHAVIOR:
+- Reads active agent from STATE.json (session.agent_active)
+- Appends a session entry to .claude/agent-memory/{slug}/MEMORY.md
+- Creates the memory file if it doesn't exist
+- Fail-open: NEVER blocks session end
+
+EXIT CODES:
+- 0: Always (advisory only, never blocks)
+
+Hook Type: SessionEnd
+"""
+
+import json
+import sys
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+
+PROJECT_ROOT = Path(os.environ.get('CLAUDE_PROJECT_DIR', '.'))
+STATE_DIR = PROJECT_ROOT / ".claude" / "jarvis"
+STATE_FILE = STATE_DIR / "STATE.json"
+AGENT_MEMORY_DIR = PROJECT_ROOT / ".claude" / "agent-memory"
+
+# Internal time budget (ms)
+INTERNAL_TIMEOUT_MS = 3000
+
+
+def load_state() -> dict:
+    """Load current state."""
+    if not STATE_FILE.exists():
+        return {}
+    try:
+        with open(STATE_FILE, 'r', encoding='utf-8') as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def get_active_agent(state: dict) -> str | None:
+    """Extract active agent slug from STATE.json."""
+    # Check session.agent_active (set by skill_router/post_tool_use)
+    session = state.get("session", {})
+    agent = session.get("agent_active")
+    if agent and isinstance(agent, str) and agent.strip():
+        return agent.strip()
+    return None
+
+
+def get_session_metadata(state: dict) -> dict:
+    """Extract useful session metadata for the memory entry."""
+    accumulated = state.get("accumulated", {})
+    pipeline = state.get("pipeline", {})
+
+    return {
+        "session_id": state.get("session_id", "unknown"),
+        "ended_at": datetime.now().isoformat(),
+        "files_processed": pipeline.get("files_processed", 0),
+        "progress_percent": accumulated.get("progress_percent", 0),
+        "current_step": pipeline.get("current_step", "unknown"),
+    }
+
+
+def get_memory_path(agent_slug: str) -> Path:
+    """Resolve agent memory path."""
+    return AGENT_MEMORY_DIR / agent_slug / "MEMORY.md"
+
+
+def create_memory_file(memory_path: Path, agent_slug: str) -> None:
+    """Create a new MEMORY.md with header."""
+    memory_path.parent.mkdir(parents=True, exist_ok=True)
+    header = f"""# {agent_slug} - Agent Memory
+
+> Auto-managed by hooks. Do not edit manually.
+> READ: skill_router.py (on activation)
+> WRITE: agent_memory_persister.py (on session end)
+
+---
+
+"""
+    memory_path.write_text(header, encoding='utf-8')
+
+
+def build_session_entry(agent_slug: str, metadata: dict) -> str:
+    """Build a markdown session entry to append to MEMORY.md."""
+    now = datetime.now()
+    date_str = now.strftime("%Y-%m-%d %H:%M")
+    session_id_short = metadata.get("session_id", "unknown")[:8]
+
+    lines = [
+        f"## Session {date_str} [{session_id_short}]",
+        "",
+        f"- **Step:** {metadata.get('current_step', 'unknown')}",
+        f"- **Progress:** {metadata.get('progress_percent', 0)}%",
+        f"- **Files processed:** {metadata.get('files_processed', 0)}",
+        "",
+        "---",
+        "",
+    ]
+
+    return "\n".join(lines)
+
+
+def append_to_memory(memory_path: Path, entry: str) -> bool:
+    """Append session entry to MEMORY.md, trimming if over 200 lines."""
+    try:
+        if not memory_path.exists():
+            return False
+
+        content = memory_path.read_text(encoding='utf-8')
+        new_content = content.rstrip('\n') + '\n\n' + entry
+
+        final_lines = new_content.split('\n')
+        if len(final_lines) > 200:
+            header = final_lines[:20]
+            recent = final_lines[-175:]
+            final_lines = header + ["", "<!-- Older entries trimmed by agent_memory_persister.py -->", ""] + recent
+
+        memory_path.write_text('\n'.join(final_lines), encoding='utf-8')
+        return True
+    except Exception:
+        return False
+
+
+def check_timeout(start_time):
+    """Check if we've exceeded internal time budget."""
+    elapsed_ms = (time.time() - start_time) * 1000
+    return elapsed_ms > INTERNAL_TIMEOUT_MS
+
+
+def main():
+    """Main hook execution with timeout protection."""
+    start_time = time.time()
+
+    try:
+        input_data = sys.stdin.read()
+        hook_input = json.loads(input_data) if input_data.strip() else {}
+
+        state = load_state()
+        if not state:
+            print(json.dumps({"continue": True}))
+            return
+
+        raw_slug = get_active_agent(state)
+        if not raw_slug:
+            print(json.dumps({"continue": True}))
+            return
+
+        if check_timeout(start_time):
+            print(json.dumps({
+                "continue": True,
+                "feedback": "[MB] Memory persister skipped (timeout after state load)"
+            }))
+            return
+
+        agent_slug = raw_slug
+        memory_path = get_memory_path(agent_slug)
+
+        if not memory_path.exists():
+            create_memory_file(memory_path, agent_slug)
+
+        if check_timeout(start_time):
+            print(json.dumps({
+                "continue": True,
+                "feedback": "[MB] Memory persister skipped (timeout before entry build)"
+            }))
+            return
+
+        metadata = get_session_metadata(state)
+        entry = build_session_entry(agent_slug, metadata)
+        success = append_to_memory(memory_path, entry)
+
+        output = {"continue": True}
+
+        if success:
+            elapsed_ms = round((time.time() - start_time) * 1000)
+            output["feedback"] = f"[MB] Session memory persisted for @{agent_slug} ({elapsed_ms}ms)"
+        else:
+            output["feedback"] = f"[MB] Could not persist memory for @{agent_slug}"
+
+        print(json.dumps(output))
+
+    except Exception as e:
+        print(json.dumps({
+            "continue": True,
+            "feedback": f"[MB] Memory persister error (fail-open): {str(e)}"
+        }))
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/claude_md_agent_sync.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+CLAUDE.md Agent Sync Hook
+Updates the Agents section in CLAUDE.md when agent structure changes.
+
+Hook Events: PostToolUse (Write/Edit to agents/ or persona-registry.yaml)
+Version: 1.0.0
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+BASE_DIR = Path(__file__).parent.parent.parent
+CLAUDE_MD = BASE_DIR / ".claude" / "CLAUDE.md"
+PERSONA_REGISTRY = BASE_DIR / "agents" / "persona-registry.yaml"
+AGENTS_DIR = BASE_DIR / "agents"
+SYNC_LOG = BASE_DIR / "logs" / "claude-md-sync.jsonl"
+
+
+def parse_stdin():
+    """Parse JSON from stdin."""
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return {}
+
+
+def should_trigger(file_path: str) -> bool:
+    """Check if this file change should trigger sync."""
+    triggers = [
+        'persona-registry.yaml',
+        'AGENT-INDEX.yaml',
+        'agents.yaml'
+    ]
+    return any(t in file_path for t in triggers)
+
+
+def count_agents() -> dict:
+    """Count agents by type."""
+    counts = {
+        'minds': 0,
+        'cargo': 0,
+        'conclave': 0,
+        'total': 0
+    }
+
+    # Count minds
+    minds_dir = AGENTS_DIR / "minds"
+    if minds_dir.exists():
+        counts['minds'] = len([d for d in minds_dir.iterdir()
+                               if d.is_dir() and not d.name.startswith('_')])
+
+    # Count conclave
+    conclave_dir = AGENTS_DIR / "conclave"
+    if conclave_dir.exists():
+        counts['conclave'] = len([d for d in conclave_dir.iterdir() if d.is_dir()])
+
+    # Count cargo (recursive)
+    cargo_dir = AGENTS_DIR / "cargo"
+    if cargo_dir.exists():
+        for group in cargo_dir.iterdir():
+            if group.is_dir():
+                counts['cargo'] += len([d for d in group.iterdir() if d.is_dir()])
+
+    counts['total'] = counts['minds'] + counts['cargo'] + counts['conclave']
+    return counts
+
+
+def update_claude_md():
+    """Update the Agents section in CLAUDE.md."""
+    if not CLAUDE_MD.exists():
+        return False
+
+    content = CLAUDE_MD.read_text()
+    counts = count_agents()
+
+    # Build new agents section
+    new_section = f"""## Agents
+
+Defined in `AGENT-INDEX.yaml`, activated via slash commands.
+
+| Type | Count | Purpose |
+|------|-------|---------|
+| CARGO | {counts['cargo']} | Functional roles (Sales, Marketing, Ops) |
+| MINDS | {counts['minds']} | Expert mind clones |
+| CONCLAVE | {counts['conclave']} | Multi-perspective deliberation |
+| SYSTEM | 2 | JARVIS, Agent-Creator |
+
+**Total Active Agents:** {counts['total']}"""
+
+    # Find and replace the Agents section
+    # Pattern matches from "## Agents" to the next "##" or end
+    pattern = r'## Agents\n.*?(?=\n## |\Z)'
+
+    if re.search(pattern, content, re.DOTALL):
+        new_content = re.sub(pattern, new_section, content, flags=re.DOTALL)
+        CLAUDE_MD.write_text(new_content)
+        return True
+
+    return False
+
+
+def log_sync(file_path: str, success: bool):
+    """Log sync operation."""
+    SYNC_LOG.parent.mkdir(parents=True, exist_ok=True)
+
+    entry = {
+        "timestamp": datetime.now().isoformat(),
+        "trigger_file": file_path,
+        "success": success,
+        "counts": count_agents()
+    }
+
+    with open(SYNC_LOG, 'a') as f:
+        f.write(json.dumps(entry) + '\n')
+
+
+def main():
+    """Main hook execution."""
+    try:
+        data = parse_stdin()
+
+        tool_name = data.get('tool_name', '')
+        tool_input = data.get('tool_input', {})
+
+        if tool_name not in ['Write', 'Edit']:
+            print(json.dumps({"continue": True}))
+            return
+
+        file_path = tool_input.get('file_path', '')
+
+        # Check if this should trigger sync
+        if not should_trigger(file_path):
+            print(json.dumps({"continue": True}))
+            return
+
+        # Update CLAUDE.md
+        success = update_claude_md()
+        log_sync(file_path, success)
+
+        if success:
+            counts = count_agents()
+            print(json.dumps({
+                "continue": True,
+                "message": f"📝 CLAUDE.md agents section synced ({counts['total']} agents)"
+            }))
+        else:
+            print(json.dumps({"continue": True}))
+
+    except Exception as e:
+        print(json.dumps({
+            "continue": True,
+            "warning": f"CLAUDE.md sync error: {str(e)}"
+        }))
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/claude_md_guard.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+CLAUDE.md Guard Hook - VETO: Blocks CLAUDE.md creation outside sanctioned locations.
+
+Hook Type: PreToolUse (Write|Edit)
+Adapted from: aios-core/.claude/hooks/claude_md_guard.py
+Date: 2026-02-18
+
+Architecture Rule Enforced:
+  CLAUDE.md files are ONLY allowed in these locations:
+  - .claude/CLAUDE.md (project instructions)
+  - CLAUDE.md (repo root)
+
+  Agent memory MUST use .claude/agent-memory/{slug}/MEMORY.md
+  NEVER create CLAUDE.md in code directories, data dirs, or subfolders.
+
+VETO CONDITIONS:
+  - Any Write/Edit targeting a CLAUDE.md outside sanctioned paths -> BLOCK
+  - Any content containing <claude-mem-context> outside .claude/ -> BLOCK
+
+ERROR HANDLING: fail-CLOSED (2026-02-22 hardening)
+  - JSONDecodeError -> BLOCK (can't parse = can't validate)
+  - Any Exception -> BLOCK (unknown error = can't validate)
+"""
+
+import json
+import sys
+import os
+from pathlib import Path
+
+# Sanctioned CLAUDE.md locations (relative to project root)
+SANCTIONED_CLAUDE_MD = {
+    "CLAUDE.md",                    # Repo root
+    ".claude/CLAUDE.md",            # Project instructions
+}
+
+# Patterns that indicate auto-generated memory spam
+SPAM_INDICATORS = [
+    "<claude-mem-context>",
+    "<!-- This section is auto-generated by claude-mem",
+    "# Recent Activity",
+]
+
+
+def normalize_path(file_path: str) -> str:
+    """Normalize path to relative, forward-slash format."""
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', '.')
+
+    fp = Path(file_path).resolve()
+    pd = Path(project_dir).resolve()
+
+    try:
+        rel = fp.relative_to(pd)
+        return str(rel).replace("\\", "/")
+    except ValueError:
+        return file_path.replace("\\", "/")
+
+
+def is_claude_md(file_path: str) -> bool:
+    """Check if the file is a CLAUDE.md file."""
+    normalized = file_path.replace("\\", "/")
+    return normalized.endswith("/CLAUDE.md") or normalized == "CLAUDE.md"
+
+
+def is_sanctioned(relative_path: str) -> bool:
+    """Check if the CLAUDE.md path is in a sanctioned location."""
+    return relative_path in SANCTIONED_CLAUDE_MD
+
+
+def content_is_spam(content: str) -> bool:
+    """Check if content contains auto-generated memory spam markers."""
+    if not content:
+        return False
+    for indicator in SPAM_INDICATORS:
+        if indicator in content:
+            return True
+    return False
+
+
+def main():
+    try:
+        input_data = sys.stdin.read()
+        if not input_data:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        hook_input = json.loads(input_data)
+        tool_name = hook_input.get("tool_name", "")
+        tool_input = hook_input.get("tool_input", {})
+
+        # Only check Write and Edit tools
+        if tool_name not in ("Write", "Edit", "write", "edit"):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        relative_path = normalize_path(file_path)
+
+        # Check if targeting a CLAUDE.md file
+        if not is_claude_md(relative_path):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Check if it's a sanctioned location
+        if is_sanctioned(relative_path):
+            content = tool_input.get("content", "")
+            if not content:
+                content = tool_input.get("new_string", "")
+
+            if content_is_spam(content):
+                print(json.dumps({
+                    "decision": "allow",
+                    "message": (
+                        "Warning: CLAUDE.md Guard: Detected claude-mem-context in sanctioned file. "
+                        "Agent memory should use .claude/agent-memory/{slug}/MEMORY.md instead."
+                    )
+                }))
+                return
+
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # UNSANCTIONED CLAUDE.md -> BLOCK
+        print(json.dumps({
+            "decision": "block",
+            "reason": (
+                f"VETO: CLAUDE.md Guard\n"
+                f"   Path: {relative_path}\n"
+                f"   Rule: CLAUDE.md files are NOT allowed outside sanctioned locations.\n"
+                f"   Sanctioned: {', '.join(sorted(SANCTIONED_CLAUDE_MD))}\n"
+                f"   Agent memory -> .claude/agent-memory/{{slug}}/MEMORY.md"
+            )
+        }))
+
+    except json.JSONDecodeError:
+        # Fail-CLOSED: can't parse input = can't validate = BLOCK
+        print(json.dumps({
+            "decision": "block",
+            "reason": "CLAUDE.md Guard: Cannot parse hook input (malformed JSON). Blocking by default."
+        }))
+    except Exception as e:
+        # Fail-CLOSED: unknown error = can't validate = BLOCK
+        print(json.dumps({
+            "decision": "block",
+            "reason": f"CLAUDE.md Guard error (fail-closed): {str(e)}. Blocking by default."
+        }))
+
+
+if __name__ == "__main__":
+    main()