@suwujs/codex-vault 0.1.0

package/plugin/hooks/classify-message.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""Classify user messages and inject routing hints.
+
+Lightweight version: 5 core signals + session-end vault integrity check.
+Agent-agnostic — outputs hookSpecificOutput compatible with both
+Claude Code and Codex CLI.
+"""
+import json
+import os
+import subprocess
+import sys
+import re
+from pathlib import Path
+
+
+SIGNALS = [
+    {
+        "name": "DECISION",
+        "message": "DECISION detected — suggest the user run /dump to capture this decision",
+        "patterns": [
+            "decided", "deciding", "decision", "we chose", "agreed to",
+            "let's go with", "the call is", "we're going with",
+        ],
+    },
+    {
+        "name": "WIN",
+        "message": "WIN detected — suggest the user run /dump to record this achievement",
+        "patterns": [
+            "achieved", "won", "praised",
+            "kudos", "shoutout", "great feedback", "recognized",
+        ],
+    },
+    {
+        "name": "PROJECT UPDATE",
+        "message": "PROJECT UPDATE detected — suggest the user run /dump to log this progress",
+        "patterns": [
+            "project update", "sprint", "milestone",
+            "shipped", "shipping", "launched", "launching",
+            "completed", "completing", "released", "releasing",
+            "deployed", "deploying",
+            "went live", "rolled out", "merged", "cut the release",
+        ],
+    },
+    {
+        "name": "QUERY",
+        "message": "QUERY detected — suggest the user run /recall to check existing knowledge first",
+        "patterns": [
+            "what is", "how does", "why did", "compare", "analyze",
+            "explain the", "what's the difference", "summarize the",
+            "relationship between",
+        ],
+    },
+    {
+        "name": "INGEST",
+        "message": "INGEST detected — suggest the user run /ingest to process the source",
+        "patterns": [
+            "ingest", "process this", "read this article",
+            "summarize this", "new source", "clip this", "web clip",
+        ],
+    },
+]
+
+SESSION_END_PATTERNS = [
+    "wrap up", "wrapping up", "that's all", "that's it",
+    "done for now", "done for today", "i'm done", "call it a day",
+    "end session", "bye", "goodbye", "good night", "see you",
+    "结束", "收工", "今天到这", "就这样",
+]
+
+
+def _match(patterns, text):
+    for phrase in patterns:
+        if re.search(r'(?<![a-zA-Z])' + re.escape(phrase) + r'(?![a-zA-Z])', text):
+            return True
+    return False
+
+
+def _find_vault_root():
+    """Find vault root from CWD — check for Home.md/brain/, then vault/ subdir."""
+    cwd = os.environ.get("CLAUDE_PROJECT_DIR",
+           os.environ.get("CODEX_PROJECT_DIR", os.getcwd()))
+    if os.path.isfile(os.path.join(cwd, "Home.md")) or os.path.isdir(os.path.join(cwd, "brain")):
+        return cwd
+    vault_sub = os.path.join(cwd, "vault")
+    if os.path.isdir(vault_sub) and (
+        os.path.isfile(os.path.join(vault_sub, "Home.md")) or
+        os.path.isdir(os.path.join(vault_sub, "brain"))
+    ):
+        return vault_sub
+    return None
+
+
+def _get_changed_files(vault_root):
+    """Get list of changed/new .md files relative to vault root."""
+    files = set()
+    try:
+        # Staged + unstaged changes
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD"],
+            capture_output=True, text=True, cwd=vault_root, timeout=5,
+        )
+        for f in result.stdout.strip().splitlines():
+            if f.endswith(".md"):
+                files.add(f)
+
+        # Untracked files
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True, text=True, cwd=vault_root, timeout=5,
+        )
+        for f in result.stdout.strip().splitlines():
+            if f.endswith(".md"):
+                files.add(f)
+    except Exception:
+        pass
+    return files
+
+
+def _check_vault_integrity(vault_root):
+    """Check for common memory-write omissions."""
+    warnings = []
+    changed = _get_changed_files(vault_root)
+    if not changed:
+        return warnings
+
+    # Check 1: New work notes but Index.md not updated
+    new_work = [f for f in changed if f.startswith("work/active/") and f != "work/Index.md"]
+    index_updated = "work/Index.md" in changed
+    if new_work and not index_updated:
+        names = ", ".join(os.path.basename(f).replace(".md", "") for f in new_work)
+        warnings.append(f"New work notes ({names}) but work/Index.md not updated")
+
+    # Check 2: Decision content written but brain/Key Decisions.md not updated
+    decision_keywords = ["decided", "decision", "agreed to", "we chose", "the call is"]
+    brain_decisions_updated = "brain/Key Decisions.md" in changed
+    if not brain_decisions_updated:
+        for f in changed:
+            if f.endswith(".md") and not f.startswith("brain/"):
+                try:
+                    content = Path(os.path.join(vault_root, f)).read_text(encoding="utf-8").lower()
+                    if any(kw in content for kw in decision_keywords):
+                        warnings.append(
+                            f"'{f}' contains decision content but brain/Key Decisions.md not updated"
+                        )
+                        break
+                except Exception:
+                    pass
+
+    # Check 3: Pattern content written but brain/Patterns.md not updated
+    pattern_keywords = ["pattern", "convention", "always do", "never do", "recurring"]
+    brain_patterns_updated = "brain/Patterns.md" in changed
+    if not brain_patterns_updated:
+        for f in changed:
+            if f.endswith(".md") and not f.startswith("brain/"):
+                try:
+                    content = Path(os.path.join(vault_root, f)).read_text(encoding="utf-8").lower()
+                    if any(kw in content for kw in pattern_keywords):
+                        warnings.append(
+                            f"'{f}' contains pattern content but brain/Patterns.md not updated"
+                        )
+                        break
+                except Exception:
+                    pass
+
+    # Check 4: operation log not updated after significant changes
+    log_updated = "log.md" in changed
+    significant_changes = len([f for f in changed
+                               if f.startswith(("work/", "reference/", "brain/"))]) >= 2
+    if significant_changes and not log_updated:
+        warnings.append("Multiple vault changes but log.md not updated")
+
+    return warnings
+
+
+def classify(prompt):
+    p = prompt.lower()
+    return [s["message"] for s in SIGNALS if _match(s["patterns"], p)]
+
+
+def is_session_end(prompt):
+    p = prompt.lower()
+    return _match(SESSION_END_PATTERNS, p)
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (ValueError, EOFError, OSError):
+        sys.exit(0)
+
+    prompt = input_data.get("prompt", "")
+    if not isinstance(prompt, str) or not prompt:
+        sys.exit(0)
+
+    messages = []
+
+    try:
+        # Regular signal classification
+        signals = classify(prompt)
+        messages.extend(signals)
+
+        # Session-end check
+        if is_session_end(prompt):
+            vault_root = _find_vault_root()
+            if vault_root:
+                integrity_warnings = _check_vault_integrity(vault_root)
+                if integrity_warnings:
+                    messages.append(
+                        "SESSION END — vault integrity check found issues:\n"
+                        + "\n".join(f"  - {w}" for w in integrity_warnings)
+                        + "\nFix these before wrapping up."
+                    )
+                else:
+                    messages.append("SESSION END — vault integrity check passed.")
+    except Exception:
+        sys.exit(0)
+
+    if messages:
+        hints = "\n".join(f"- {s}" for s in messages)
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": (
+                    "Skill suggestions (do NOT auto-execute — suggest the skill to the user and let them decide):\n"
+                    + hints
+                    + "\n\nWait for the user to invoke the skill. Do not create vault notes without explicit user action."
+                )
+            }
+        }
+        json.dump(output, sys.stdout)
+        sys.stdout.flush()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        sys.exit(0)

package/plugin/hooks/session-start.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+set -eo pipefail
+
+# Codex-Vault session-start hook
+# Injects vault context into the agent's prompt at session start.
+# Works with any agent that supports SessionStart hooks (Claude Code, Codex CLI).
+#
+# Dynamic context: adapts git log window, reads full North Star,
+# shows all active work, and includes uncommitted changes.
+
+VAULT_DIR="${CLAUDE_PROJECT_DIR:-${CODEX_PROJECT_DIR:-$(pwd)}}"
+cd "$VAULT_DIR"
+
+# Find vault root (look for Home.md or brain/ directory)
+if [ ! -f "Home.md" ] && [ ! -d "brain/" ]; then
+  # Try vault/ subdirectory (integrated layout)
+  if [ -d "vault/" ]; then
+    VAULT_DIR="$VAULT_DIR/vault"
+    cd "$VAULT_DIR"
+  fi
+fi
+
+echo "## Session Context"
+echo ""
+echo "### Date"
+echo "$(date +%Y-%m-%d) ($(date +%A))"
+echo ""
+
+# North Star — full file (should be concise by design)
+echo "### North Star"
+if [ -f "brain/North Star.md" ]; then
+  cat "brain/North Star.md"
+else
+  echo "(No North Star found — create brain/North Star.md to set goals)"
+fi
+echo ""
+
+# Recent changes — adaptive window
+echo "### Recent Changes"
+COMMITS_48H=$(git log --oneline --since="48 hours ago" --no-merges 2>/dev/null | wc -l | tr -d ' ')
+if [ "$COMMITS_48H" -gt 0 ]; then
+  echo "(last 48 hours)"
+  git log --oneline --since="48 hours ago" --no-merges 2>/dev/null | head -15 || true
+else
+  COMMITS_7D=$(git log --oneline --since="7 days ago" --no-merges 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$COMMITS_7D" -gt 0 ]; then
+    echo "(nothing in 48h — showing last 7 days)"
+    git log --oneline --since="7 days ago" --no-merges 2>/dev/null | head -15 || true
+  else
+    echo "(nothing recent — showing last 5 commits)"
+    git log --oneline -5 --no-merges 2>/dev/null || echo "(no git history)"
+  fi
+fi
+echo ""
+
+# Recent operations from log — adaptive
+echo "### Recent Operations"
+if [ -f "log.md" ]; then
+  ENTRY_COUNT=$(grep -c "^## \[" "log.md" 2>/dev/null || echo "0")
+  if [ "$ENTRY_COUNT" -gt 0 ]; then
+    # Show last 5 entries with full header line (includes date + type)
+    grep "^## \[" "log.md" | tail -5
+  else
+    echo "(no entries in log.md)"
+  fi
+else
+  echo "(no log.md)"
+fi
+echo ""
+
+# Active work — show all (this is the current focus, no truncation)
+echo "### Active Work"
+if [ -d "work/active" ]; then
+  WORK_FILES=$(ls work/active/*.md 2>/dev/null || true)
+  if [ -n "$WORK_FILES" ]; then
+    echo "$WORK_FILES" | sed 's|work/active/||;s|\.md$||'
+  else
+    echo "(none)"
+  fi
+else
+  echo "(no work/active/ directory)"
+fi
+echo ""
+
+# Uncommitted changes — shows agent what's in-flight
+echo "### Uncommitted Changes"
+CHANGES=$(git status --short -- . 2>/dev/null | head -20 || true)
+if [ -n "$CHANGES" ]; then
+  echo "$CHANGES"
+else
+  echo "(working tree clean)"
+fi
+echo ""
+
+# Recently modified brain files — highlights memory that may need review
+echo "### Recently Modified Brain Files"
+if [ -d "brain" ]; then
+  GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo "")
+  if [ -n "$GIT_DIR" ] && [ -f "$GIT_DIR/index" ]; then
+    RECENT_BRAIN=$(find brain/ -name "*.md" -newer "$GIT_DIR/index" 2>/dev/null || true)
+  else
+    RECENT_BRAIN=""
+  fi
+  if [ -n "$RECENT_BRAIN" ]; then
+    echo "$RECENT_BRAIN" | sed 's|brain/||;s|\.md$||'
+  else
+    # Fallback: show brain files modified in last 7 days
+    RECENT_BRAIN=$(find brain/ -name "*.md" -mtime -7 2>/dev/null || true)
+    if [ -n "$RECENT_BRAIN" ]; then
+      echo "(modified in last 7 days)"
+      echo "$RECENT_BRAIN" | sed 's|brain/||;s|\.md$||'
+    else
+      echo "(no recent changes)"
+    fi
+  fi
+fi
+echo ""
+
+# Vault file listing — tiered to avoid flooding context in large vaults
+echo "### Vault Files"
+ALL_FILES=$(find . -name "*.md" -not -path "./.git/*" -not -path "./.obsidian/*" -not -path "./thinking/*" -not -path "./.claude/*" -not -path "./.codex/*" -not -path "./.codex-vault/*" -not -path "./node_modules/*" 2>/dev/null | sort)
+FILE_COUNT=$(echo "$ALL_FILES" | grep -c . 2>/dev/null || echo "0")
+
+_folder_summary() {
+  echo "$ALL_FILES" | sed 's|^\./||' | cut -d/ -f1 | sort | uniq -c | sort -rn | while read count dir; do
+    echo "  $dir/ ($count files)"
+  done
+}
+
+_key_files() {
+  echo "$ALL_FILES" | grep -E "(Home|Index|North Star|Memories|Key Decisions|Patterns|log)\\.md$" || true
+}
+
+if [ "$FILE_COUNT" -le 20 ]; then
+  # Tier 1: small vault — list everything
+  echo "$ALL_FILES"
+
+elif [ "$FILE_COUNT" -le 50 ]; then
+  # Tier 2: medium vault — list hot folders, summarize cold storage
+  HOT_FILES=$(echo "$ALL_FILES" | grep -v -E "^\./sources/|^\./work/archive/" || true)
+  COLD_COUNT=$(echo "$ALL_FILES" | grep -E "^\./sources/|^\./work/archive/" | grep -c . 2>/dev/null || echo "0")
+
+  if [ -n "$HOT_FILES" ]; then
+    echo "$HOT_FILES"
+  fi
+  if [ "$COLD_COUNT" -gt 0 ]; then
+    echo ""
+    echo "(+ $COLD_COUNT files in sources/ and work/archive/ — use /recall to search)"
+  fi
+
+elif [ "$FILE_COUNT" -le 150 ]; then
+  # Tier 3: large vault — folder summary + recent + key files
+  echo "($FILE_COUNT files — showing summary)"
+  echo ""
+  _folder_summary
+  echo ""
+  echo "Recently modified (7 days):"
+  find . -name "*.md" -mtime -7 -not -path "./.git/*" -not -path "./.obsidian/*" -not -path "./thinking/*" -not -path "./.claude/*" -not -path "./.codex/*" -not -path "./.codex-vault/*" -not -path "./node_modules/*" 2>/dev/null | sort || echo "  (none)"
+  echo ""
+  echo "Key files:"
+  _key_files
+
+else
+  # Tier 4: very large vault — minimal footprint
+  echo "($FILE_COUNT files — showing summary)"
+  echo ""
+  _folder_summary
+  echo ""
+  echo "Recently modified (3 days):"
+  find . -name "*.md" -mtime -3 -not -path "./.git/*" -not -path "./.obsidian/*" -not -path "./thinking/*" -not -path "./.claude/*" -not -path "./.codex/*" -not -path "./.codex-vault/*" -not -path "./node_modules/*" 2>/dev/null | sort || echo "  (none)"
+  echo ""
+  echo "Key files:"
+  _key_files
+  echo ""
+  echo "Use /recall <topic> to search the vault."
+fi

package/plugin/hooks/validate-write.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Post-write validation for vault notes.
+
+Checks frontmatter and wikilinks on any .md file written to the vault.
+Agent-agnostic — outputs hookSpecificOutput compatible with both
+Claude Code and Codex CLI.
+"""
+import json
+import re
+import sys
+import os
+from pathlib import Path
+
+
+def _check_log_format(content):
+    """Validate log.md entry format: ## [YYYY-MM-DD] <type> | <title>"""
+    warnings = []
+    for i, line in enumerate(content.splitlines(), 1):
+        if line.startswith("## ") and not line.startswith("## ["):
+            # Heading that looks like a log entry but missing date brackets
+            if any(t in line.lower() for t in ["ingest", "session", "query", "maintenance", "decision", "archive"]):
+                warnings.append(f"Line {i}: log entry missing date format — expected `## [YYYY-MM-DD] <type> | <title>`")
+        elif line.startswith("## ["):
+            if not re.match(r"^## \[\d{4}-\d{2}-\d{2}\] \w+", line):
+                warnings.append(f"Line {i}: malformed log entry — expected `## [YYYY-MM-DD] <type> | <title>`")
+    return warnings
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (ValueError, EOFError, OSError):
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input")
+    if not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        sys.exit(0)
+
+    if not file_path.endswith(".md"):
+        sys.exit(0)
+
+    normalized = file_path.replace("\\", "/")
+    basename = os.path.basename(normalized)
+
+    # Skip non-vault files
+    skip_names = {"README.md", "CHANGELOG.md", "CONTRIBUTING.md", "CLAUDE.md", "AGENTS.md", "LICENSE"}
+    if basename in skip_names:
+        sys.exit(0)
+    if basename.startswith("README.") and basename.endswith(".md"):
+        sys.exit(0)
+
+    skip_paths = [".claude/", ".codex/", ".codex-vault/", ".mind/", "templates/", "thinking/", "node_modules/", "plugin/", "docs/"]
+    if any(skip in normalized for skip in skip_paths):
+        sys.exit(0)
+
+    warnings = []
+
+    try:
+        content = Path(file_path).read_text(encoding="utf-8")
+
+        if not content.startswith("---"):
+            warnings.append("Missing YAML frontmatter")
+        else:
+            parts = content.split("---", 2)
+            if len(parts) >= 3:
+                fm = parts[1]
+                if "date:" not in fm and basename != "log.md":
+                    warnings.append("Missing `date` in frontmatter")
+                if "tags:" not in fm:
+                    warnings.append("Missing `tags` in frontmatter")
+                if "description:" not in fm:
+                    warnings.append("Missing `description` in frontmatter (~150 chars)")
+
+        if len(content) > 300 and "[[" not in content:
+            warnings.append("No [[wikilinks]] found — every note should link to at least one other note")
+
+        # Check for unfilled template placeholders
+        placeholders = re.findall(r"\{\{[^}]+\}\}", content)
+        if placeholders:
+            examples = ", ".join(placeholders[:3])
+            warnings.append(f"Unfilled template placeholders found: {examples}")
+
+        # Validate log.md format
+        if basename == "log.md":
+            log_warnings = _check_log_format(content)
+            warnings.extend(log_warnings)
+
+    except Exception:
+        sys.exit(0)
+
+    if warnings:
+        hint_list = "\n".join(f"  - {w}" for w in warnings)
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": f"Vault warnings for `{basename}`:\n{hint_list}\nFix these before moving on."
+            }
+        }
+        json.dump(output, sys.stdout)
+        sys.stdout.flush()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        sys.exit(0)