@suwujs/codex-vault 0.1.0

package/vault/.claude/skills/dump/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: dump
+description: "Freeform capture — dump anything (notes, ideas, decisions, links) and it gets classified and routed to the right vault location. Triggers: 'dump this', 'capture', 'save this thought', 'note this down', 'remember this', 'jot down'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Process the following freeform dump. For each distinct piece of information:
+
+1. **Classify** it: decision, project update, win/achievement, or general work note.
+2. **Search first**: Check if a related note already exists. Prefer updating over creating.
+3. **Create or update** the appropriate note:
+   - Correct folder (work/active/, brain/, etc.)
+   - Full YAML frontmatter (date, description, tags)
+   - All relevant [[wikilinks]]
+4. **Update indexes**: `work/Index.md`, `brain/` notes as needed.
+5. **Cross-link**: Every new note links to at least one existing note.
+
+After processing, summarize:
+- What was captured and where
+- New notes created (with paths)
+- Existing notes updated
+- Anything unclear (ask the user)
+
+Content to process:
+$ARGUMENTS

package/vault/.claude/skills/ingest/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ingest
+description: "Import external content (URLs, files, text) into the vault as structured source notes. Triggers: 'ingest', 'import this', 'save this article', 'add source', 'read and save'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Ingest a source into the vault. Follow these steps:
+
+### 1. Locate the Source
+
+The user provides either:
+- A filename in `sources/` (e.g., `sources/karpathy-llm-wiki.md`)
+- A URL to fetch (use `defuddle parse <url> --md` or `curl` to save to `sources/` first)
+
+If a URL, save the raw content to `sources/` before proceeding — sources are the immutable record.
+
+### 2. Read the Source
+
+Read the full source document. Do not skim — ingestion depends on thorough reading.
+
+### 3. Discuss Key Takeaways
+
+Present the top 3-5 takeaways to the user. Ask:
+- Which points are most relevant to current work?
+- Any connections to existing vault notes?
+- Anything to skip or emphasize?
+
+Wait for user input before proceeding.
+
+### 4. Create a Source Summary
+
+Create a note in `work/active/` using the **Source Summary** template:
+- Fill in all YAML frontmatter (date, description, source, tags)
+- Write Key Takeaways, Summary, Connections (with [[wikilinks]]), Quotes/Data Points
+- The `source` field should reference the file in `sources/` or the original URL
+
+### 5. Update Indexes
+
+- Add the summary to `work/Index.md` under a "Sources" section (create the section if it doesn't exist)
+- Update relevant `brain/` notes if the source contains decisions (`Key Decisions.md`), patterns (`Patterns.md`), or context worth remembering (`Memories.md`)
+
+### 6. Cross-Link
+
+Check existing vault notes for connections:
+- Do any active projects relate to this source?
+- Does the source reinforce or challenge any existing decisions?
+- Add [[wikilinks]] in both directions where relevant
+
+### 7. Report
+
+Summarize what was done:
+- Source file location
+- Summary note created (path)
+- Indexes updated
+- Cross-links added
+- Brain notes updated (if any)
+
+Source to process:
+$ARGUMENTS

package/vault/.claude/skills/recall/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: recall
+description: "Search vault memory for a topic — finds relevant notes across brain, work, reference, and sources. Triggers: 'recall', 'what do I know about', 'search memory', 'find notes about', 'look up'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Search the vault for information about the given topic.
+
+### 1. Parse the Query
+
+Extract the key topic or question from the user's input.
+
+### 2. Search the Vault
+
+Two-pass search — semantic first, keyword fallback:
+
+**Pass 1 — Frontmatter scan (semantic):**
+Read the first 5 lines (YAML frontmatter) of every `.md` file in the vault. Use the `description` and `tags` fields to judge relevance semantically — match by meaning, not just keywords. For example, a query about "caching" should match a note with description "Redis selection for session storage".
+
+Scan in priority order:
+1. `brain/` — persistent memory
+2. `work/active/` — current projects
+3. `reference/` — saved analyses
+4. `work/archive/` — completed work
+5. `sources/` — raw source documents
+
+**Pass 2 — Keyword grep (fallback):**
+If Pass 1 finds fewer than 2 relevant files, supplement with a keyword grep across file contents.
+
+### 3. Read Matches
+
+Read the top 3-5 relevant files in full. Prioritize files where the topic appears in:
+- The description or tags (strongest signal)
+- Headings
+- Multiple times in the body
+
+### 4. Synthesize
+
+Present what the vault knows about this topic:
+- **Found in**: list the files (as [[wikilinks]])
+- **Summary**: synthesize the relevant information across all matches
+- **Connections**: note any links between the matched notes
+- **Gaps**: flag if the vault has limited or no information on this topic
+
+### 5. Offer Writeback
+
+If the synthesis is substantial (combines 3+ sources), offer to save it as a reference note.
+
+Topic to recall:
+$ARGUMENTS

package/vault/.claude/skills/wrap-up/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: wrap-up
+description: "End-of-session wrap-up — commits changes, updates indexes, captures decisions made. Triggers: 'wrap up', 'end session', 'save progress', 'commit and close', 'done for today'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Session wrap-up. Review what was done and leave the vault clean.
+
+### 1. Review
+Scan the conversation for notes created or modified. List them all.
+
+### 2. Verify Quality
+For each note: frontmatter complete? At least one [[wikilink]]? Correct folder?
+
+### 3. Check Indexes
+- `work/Index.md` — new notes linked? Completed projects moved?
+- `brain/Memories.md` — Recent Context updated?
+- `brain/Key Decisions.md` — new decisions captured?
+- `brain/Patterns.md` — new patterns observed?
+
+### 4. Check for Orphans
+Any new notes not linked from at least one other note?
+
+### 5. Archive Check
+Notes in `work/active/` that should move to `work/archive/`?
+
+### 6. Report
+- **Done**: what was captured
+- **Fixed**: issues resolved
+- **Flagged**: needs user input
+- **Suggested**: improvements for next time

package/vault/.codex/config.toml

@@ -0,0 +1,2 @@
+[features]
+codex_hooks = true

package/vault/.codex/hooks.json

@@ -0,0 +1,39 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .codex-vault/hooks/session-start.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .codex-vault/hooks/classify-message.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .codex-vault/hooks/validate-write.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/vault/.codex/skills/dump/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: dump
+description: "Freeform capture — dump anything (notes, ideas, decisions, links) and it gets classified and routed to the right vault location. Triggers: 'dump this', 'capture', 'save this thought', 'note this down', 'remember this', 'jot down'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Process the following freeform dump. For each distinct piece of information:
+
+1. **Classify** it: decision, project update, win/achievement, or general work note.
+2. **Search first**: Check if a related note already exists. Prefer updating over creating.
+3. **Create or update** the appropriate note:
+   - Correct folder (work/active/, brain/, etc.)
+   - Full YAML frontmatter (date, description, tags)
+   - All relevant [[wikilinks]]
+4. **Update indexes**: `work/Index.md`, `brain/` notes as needed.
+5. **Cross-link**: Every new note links to at least one existing note.
+
+After processing, summarize:
+- What was captured and where
+- New notes created (with paths)
+- Existing notes updated
+- Anything unclear (ask the user)
+
+Content to process:
+$ARGUMENTS

package/vault/.codex/skills/ingest/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ingest
+description: "Import external content (URLs, files, text) into the vault as structured source notes. Triggers: 'ingest', 'import this', 'save this article', 'add source', 'read and save'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Ingest a source into the vault. Follow these steps:
+
+### 1. Locate the Source
+
+The user provides either:
+- A filename in `sources/` (e.g., `sources/karpathy-llm-wiki.md`)
+- A URL to fetch (use `defuddle parse <url> --md` or `curl` to save to `sources/` first)
+
+If a URL, save the raw content to `sources/` before proceeding — sources are the immutable record.
+
+### 2. Read the Source
+
+Read the full source document. Do not skim — ingestion depends on thorough reading.
+
+### 3. Discuss Key Takeaways
+
+Present the top 3-5 takeaways to the user. Ask:
+- Which points are most relevant to current work?
+- Any connections to existing vault notes?
+- Anything to skip or emphasize?
+
+Wait for user input before proceeding.
+
+### 4. Create a Source Summary
+
+Create a note in `work/active/` using the **Source Summary** template:
+- Fill in all YAML frontmatter (date, description, source, tags)
+- Write Key Takeaways, Summary, Connections (with [[wikilinks]]), Quotes/Data Points
+- The `source` field should reference the file in `sources/` or the original URL
+
+### 5. Update Indexes
+
+- Add the summary to `work/Index.md` under a "Sources" section (create the section if it doesn't exist)
+- Update relevant `brain/` notes if the source contains decisions (`Key Decisions.md`), patterns (`Patterns.md`), or context worth remembering (`Memories.md`)
+
+### 6. Cross-Link
+
+Check existing vault notes for connections:
+- Do any active projects relate to this source?
+- Does the source reinforce or challenge any existing decisions?
+- Add [[wikilinks]] in both directions where relevant
+
+### 7. Report
+
+Summarize what was done:
+- Source file location
+- Summary note created (path)
+- Indexes updated
+- Cross-links added
+- Brain notes updated (if any)
+
+Source to process:
+$ARGUMENTS

package/vault/.codex/skills/recall/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: recall
+description: "Search vault memory for a topic — finds relevant notes across brain, work, reference, and sources. Triggers: 'recall', 'what do I know about', 'search memory', 'find notes about', 'look up'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Search the vault for information about the given topic.
+
+### 1. Parse the Query
+
+Extract the key topic or question from the user's input.
+
+### 2. Search the Vault
+
+Two-pass search — semantic first, keyword fallback:
+
+**Pass 1 — Frontmatter scan (semantic):**
+Read the first 5 lines (YAML frontmatter) of every `.md` file in the vault. Use the `description` and `tags` fields to judge relevance semantically — match by meaning, not just keywords. For example, a query about "caching" should match a note with description "Redis selection for session storage".
+
+Scan in priority order:
+1. `brain/` — persistent memory
+2. `work/active/` — current projects
+3. `reference/` — saved analyses
+4. `work/archive/` — completed work
+5. `sources/` — raw source documents
+
+**Pass 2 — Keyword grep (fallback):**
+If Pass 1 finds fewer than 2 relevant files, supplement with a keyword grep across file contents.
+
+### 3. Read Matches
+
+Read the top 3-5 relevant files in full. Prioritize files where the topic appears in:
+- The description or tags (strongest signal)
+- Headings
+- Multiple times in the body
+
+### 4. Synthesize
+
+Present what the vault knows about this topic:
+- **Found in**: list the files (as [[wikilinks]])
+- **Summary**: synthesize the relevant information across all matches
+- **Connections**: note any links between the matched notes
+- **Gaps**: flag if the vault has limited or no information on this topic
+
+### 5. Offer Writeback
+
+If the synthesis is substantial (combines 3+ sources), offer to save it as a reference note.
+
+Topic to recall:
+$ARGUMENTS

package/vault/.codex/skills/wrap-up/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: wrap-up
+description: "End-of-session wrap-up — commits changes, updates indexes, captures decisions made. Triggers: 'wrap up', 'end session', 'save progress', 'commit and close', 'done for today'."
+license: MIT
+metadata:
+  author: sukbearai
+  version: "1.0.0"
+  homepage: "https://github.com/sukbearai/codex-vault"
+---
+
+Session wrap-up. Review what was done and leave the vault clean.
+
+### 1. Review
+Scan the conversation for notes created or modified. List them all.
+
+### 2. Verify Quality
+For each note: frontmatter complete? At least one [[wikilink]]? Correct folder?
+
+### 3. Check Indexes
+- `work/Index.md` — new notes linked? Completed projects moved?
+- `brain/Memories.md` — Recent Context updated?
+- `brain/Key Decisions.md` — new decisions captured?
+- `brain/Patterns.md` — new patterns observed?
+
+### 4. Check for Orphans
+Any new notes not linked from at least one other note?
+
+### 5. Archive Check
+Notes in `work/active/` that should move to `work/archive/`?
+
+### 6. Report
+- **Done**: what was captured
+- **Fixed**: issues resolved
+- **Flagged**: needs user input
+- **Suggested**: improvements for next time

package/vault/.codex-vault/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)