kyp-mem 0.2.2 → 0.3.0

package/README.md

@@ -1,49 +1,59 @@
 # KYP-MEM — Know Your Project Memory
 
-**Headless knowledge base for AI agents.** Markdown notes with wikilinks, backlinks, tags, related notes, and a neon web UI — all powered by an MCP server so Claude (or any AI) can read and write your project knowledge directly.
+**Persistent knowledge base for AI agents.** Markdown vault with wikilinks, backlinks, tags, graph navigation, and auto-learning — all powered by an MCP server so Claude (or any AI) can read and write project knowledge across sessions.
 
 ## Install
 
 ```bash
-npx -y kyp-mem
+npm install -g kyp-mem
 ```
 
-Or install the command globally:
+Or run directly:
 
 ```bash
-npm install -g kyp-mem
+npx -y kyp-mem
 ```
 
-## Setup (3 commands)
+## Setup
 
 ```bash
-# 1. Choose where your vault (knowledge base) lives
-npx -y kyp-mem init
+kyp-mem init            # Choose vault location
+kyp-mem setup-claude    # Auto-configure Claude Code MCP
+kyp-mem install-hooks   # Enable auto-learning from sessions
+```
+
+Restart Claude Code. Done — kyp-mem runs headlessly every session with 9 tools available.
 
-# 2. Connect to Claude Code — auto-configures MCP
-npx -y kyp-mem setup-claude
+## Auto-Learning
 
-# 3. Restart Claude Code — done!
-#    kyp-mem now runs headlessly every session.
-#    Claude can read/write/search your knowledge base.
+KYP-MEM can automatically capture what happens in every Claude Code session:
+
+```bash
+kyp-mem install-hooks --global
 ```
 
-That's it. Claude now has `kyp_read`, `kyp_write`, `kyp_search`, and 7 other tools available in every session.
+This installs two hooks:
+- **PostToolUse** — captures file edits, writes, and commands (pure Node, fast)
+- **Stop** — compiles session activity into a vault note under `Sessions/`
 
-## Optional: Web UI
+Sessions with fewer than 3 substantive actions are automatically skipped.
+
+## Web UI
 
 ```bash
-npx -y kyp-mem ui
+kyp-mem ui
 ```
 
-Opens a rich interface at `localhost:3333` with:
-- Collapsible folder tree
-- Rendered markdown with syntax highlighting
-- Clickable `[[wikilinks]]`
-- Backlinks and related notes panel
-- Interactive D3 graph view (toggleable)
+Opens at `localhost:3333` with:
+- Quick switcher (`Cmd+O`) — fuzzy jump to any note
 - Full-text search (`Cmd+K`)
-- Draggable resizable panels
+- Tag filtering — clickable tag cloud, AND-filter
+- Outline panel — heading TOC with click-to-scroll
+- Backlink context — shows the surrounding line
+- Unlinked mentions — finds references without `[[wikilinks]]`
+- Inline editing — edit notes directly in the browser (`Cmd+S`)
+- Local graph view — D3 force-directed graph of connections
+- Resizable panels, collapsible tree, rendered markdown
 
 ## How It Works
 
@@ -55,85 +65,74 @@ Opens a rich interface at `localhost:3333` with:
                                                    └──────────────┘
 ```
 
-- **Headless by default** — runs as an MCP server (stdio), no GUI needed
-- **Markdown files on disk** — plain `.md` files with YAML frontmatter, no database
-- **In-memory index** — links, backlinks, tags, search, similarity scoring
-- **Web UI optional** — `kyp-mem ui` when you want to browse visually
+- **Headless by default** — MCP server over stdio, no GUI needed
+- **Markdown on disk** — plain `.md` files with YAML frontmatter, no database
+- **In-memory index** — wikilinks, backlinks, tags, word-level search index
+- **Lightweight reads** — brief mode by default (~100 tokens), full content opt-in
+- **Graph navigation** — follow `[[links]]` instead of searching broadly
 
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
 | `kyp-mem init` | First-time setup — choose vault location |
-| `kyp-mem setup-claude` | Register the MCP server with Claude Code for this project |
+| `kyp-mem setup-claude` | Register MCP server with Claude Code |
 | `kyp-mem setup-claude --global` | Configure globally (all projects) |
+| `kyp-mem install-hooks` | Enable auto-learning from sessions |
+| `kyp-mem install-hooks --remove` | Remove auto-learning hooks |
 | `kyp-mem serve` | Start MCP server (used by Claude, not you) |
 | `kyp-mem ui` | Open web UI at localhost:3333 |
 | `kyp-mem stats` | Print vault statistics |
 | `kyp-mem tree` | Print vault tree |
 | `kyp-mem doctor` | Check installation health |
 
-## MCP Tools (what Claude gets)
+## MCP Tools (9 tools)
 
 | Tool | Description |
 |------|-------------|
-| `kyp_list` | Browse vault folders and notes |
-| `kyp_read` | Read a note — content + tags + backlinks + related |
+| `kyp_list` | Browse folders and notes with inline tags |
+| `kyp_read` | Brief summary by default; `full=True` for complete content |
 | `kyp_write` | Create or update a note with tags and properties |
 | `kyp_delete` | Delete a note |
-| `kyp_search` | Full-text search across all notes |
+| `kyp_search` | Full-text search with optional tag filter |
 | `kyp_tags` | List all tags or filter notes by tag |
-| `kyp_related` | Find related notes by links, tags, proximity |
+| `kyp_related` | Find related notes by links, tags, folder proximity |
 | `kyp_recent` | Recently modified notes |
 | `kyp_stats` | Vault statistics |
 
 ## Note Format
 
-Standard markdown with YAML frontmatter:
-
 ```markdown
 ---
 tags: [project, trading, config]
-source: config.py
 created: 2026-05-12
-updated: 2026-05-12
 ---
 
 # Configuration
 
-Settings are defined in `HedgeConfig`. See [[Risk Management]] for safety checks.
+Settings are in `HedgeConfig`. See [[Risk Management]] for safety checks.
 ```
 
-`[[Wikilinks]]` are automatically parsed, indexed, and turned into navigable backlinks.
+`[[Wikilinks]]` are parsed, indexed, and resolved into navigable backlinks automatically.
 
 ## Manual Claude Code Config
 
-If you prefer to configure manually instead of using `setup-claude`:
-
 ```bash
-claude mcp add -s local -e KYP_VAULT="$HOME/.kyp-mem/vault" kyp-mem -- npx -y kyp-mem serve
+claude mcp add -s user -e KYP_VAULT="$HOME/.kyp-mem/vault" kyp-mem -- npx -y kyp-mem serve
 ```
 
-Use `-s user` instead of `-s local` to make it available in all projects.
-
 ## Architecture
 
 ```
 ~/.kyp-mem/
-├── config.json       # vault path + settings
-└── vault/            # your knowledge base
+├── config.json       # vault path
+├── sessions/         # auto-learning session logs
+└── vault/
     ├── Project A/
     │   ├── Architecture.md
-    │   ├── Configuration.md
     │   └── Bugs.md
-    └── Project B/
-        └── ...
-```
-
-## Publishing to npm
-
-```bash
-npm publish
+    ├── Sessions/     # auto-captured session notes
+    └── ...
 ```
 
 ## License

package/bin/cli.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "child_process";
-import { delimiter, dirname, resolve } from "path";
+import { appendFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { delimiter, dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 
 const args = process.argv.slice(2);
@@ -47,6 +49,59 @@ function findPython() {
   return null;
 }
 
+// --- Hook fast path (pure Node, no Python startup) ---
+if (args[0] === "hook") {
+  const hookType = args[1];
+  const sessionDir = join(homedir(), ".kyp-mem", "sessions");
+  const sessionFile = join(sessionDir, "current.jsonl");
+
+  const chunks = [];
+  process.stdin.on("data", (chunk) => chunks.push(chunk));
+  await new Promise((r) => process.stdin.on("end", r));
+  const raw = Buffer.concat(chunks).toString();
+
+  if (hookType === "post-tool-use") {
+    try {
+      const data = JSON.parse(raw);
+      const tool = data.tool_name || "";
+      if (tool.includes("kyp-mem") || tool.includes("kyp_mem")) process.exit(0);
+
+      const input = data.tool_input || {};
+      const entry = { ts: new Date().toISOString(), tool, cwd: process.cwd() };
+
+      if (tool === "Edit" || tool === "Write") {
+        entry.file = input.file_path || "";
+        entry.action = tool === "Edit" ? "edit" : "create";
+      } else if (tool === "Bash") {
+        entry.command = (input.command || "").slice(0, 300);
+        entry.action = "command";
+      } else {
+        entry.action = "other";
+        entry.detail = tool;
+      }
+
+      mkdirSync(sessionDir, { recursive: true });
+      appendFileSync(sessionFile, JSON.stringify(entry) + "\n");
+    } catch (_) {
+      // silent — hooks must never break the flow
+    }
+    process.exit(0);
+  }
+
+  if (hookType === "stop") {
+    const py = findPython();
+    if (py) {
+      const [cmd, pre] = py;
+      const r = run(cmd, [...pre, "-m", "kyp_mem.hooks", "stop"], "inherit");
+      process.exit(r.status ?? 0);
+    }
+    process.exit(0);
+  }
+
+  console.error("Unknown hook type:", hookType);
+  process.exit(1);
+}
+
 const python = findPython();
 
 if (python) {

package/kyp_mem/__init__.py

@@ -1,3 +1,3 @@
 """KYP-MEM — Know Your Project Memory. Headless knowledge base for AI agents."""
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

package/kyp_mem/cli.py

@@ -36,6 +36,11 @@ def main():
 
     subparsers.add_parser("stats", help="Print vault statistics")
     subparsers.add_parser("tree", help="Print vault tree")
+    ih = subparsers.add_parser("install-hooks", help="Set up auto-learning hooks for Claude Code")
+    ih.add_argument("--global", dest="global_config", action="store_true",
+                    help="Add hooks to global ~/.claude/settings.json (default: project)")
+    ih.add_argument("--remove", action="store_true", help="Remove KYP-MEM hooks")
+
     subparsers.add_parser("doctor", help="Check installation and config health")
 
     args = parser.parse_args()
@@ -57,6 +62,8 @@ def main():
         _run_stats()
     elif args.command == "tree":
         _run_tree()
+    elif args.command == "install-hooks":
+        _run_install_hooks(global_config=args.global_config, remove=args.remove)
     elif args.command == "doctor":
         _run_doctor()
     else:
@@ -237,6 +244,78 @@ def _write_legacy_claude_settings(
     return settings_path
 
 
+def _run_install_hooks(global_config: bool = False, remove: bool = False):
+    mcp_command, _ = _get_mcp_command()
+
+    if global_config:
+        settings_path = Path.home() / ".claude" / "settings.json"
+        scope_label = "global"
+    else:
+        settings_path = Path.cwd() / ".claude" / "settings.json"
+        scope_label = "project"
+
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings = {}
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text())
+        except json.JSONDecodeError:
+            settings = {}
+
+    hooks = settings.setdefault("hooks", {})
+
+    if remove:
+        changed = False
+        for event in ("PostToolUse", "Stop"):
+            if event in hooks:
+                hooks[event] = [h for h in hooks[event] if "kyp-mem hook" not in h.get("command", "")]
+                if not hooks[event]:
+                    del hooks[event]
+                changed = True
+        if not hooks:
+            del settings["hooks"]
+        settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+        print()
+        print(f"  {G}✓{R} KYP-MEM hooks removed from {scope_label} settings")
+        print(f"  {D}  File: {settings_path}{R}")
+        print()
+        return
+
+    post_tool_hooks = hooks.setdefault("PostToolUse", [])
+    stop_hooks = hooks.setdefault("Stop", [])
+
+    post_tool_hooks = [h for h in post_tool_hooks if "kyp-mem hook" not in h.get("command", "")]
+    stop_hooks = [h for h in stop_hooks if "kyp-mem hook" not in h.get("command", "")]
+
+    post_tool_hooks.append({
+        "matcher": "Edit|Write|Bash",
+        "hooks": [{"type": "command", "command": f"{mcp_command} hook post-tool-use"}],
+    })
+    stop_hooks.append({
+        "hooks": [{"type": "command", "command": f"{mcp_command} hook stop"}],
+    })
+
+    hooks["PostToolUse"] = post_tool_hooks
+    hooks["Stop"] = stop_hooks
+
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+
+    print()
+    print(f"  {C}KYP-MEM{R} — Auto-Learning Hooks")
+    print()
+    print(f"  {G}✓{R} Hooks installed ({scope_label})")
+    print(f"  {D}  File: {settings_path}{R}")
+    print()
+    print(f"  How it works:")
+    print(f"  {D}  • PostToolUse hook captures file edits, writes, and commands{R}")
+    print(f"  {D}  • Stop hook compiles the session into a vault note{R}")
+    print(f"  {D}  • Notes saved under Sessions/ with timestamps and tags{R}")
+    print(f"  {D}  • Sessions with < 3 substantive actions are skipped{R}")
+    print()
+    print(f"  {C}Done!{R} Restart Claude Code. Sessions will auto-save to your vault.")
+    print()
+
+
 def _run_stats():
     from .config import get_vault_path
     from .vault import Vault
@@ -314,6 +393,28 @@ def _run_doctor():
         if "kyp-mem" in s.get("mcpServers", {}):
             print(f"  {D}·{R} Legacy Claude settings ({label}): kyp-mem entry present")
 
+    # Hooks
+    for label, path in legacy_paths:
+        if not path.exists():
+            continue
+        try:
+            s = json.loads(path.read_text())
+        except json.JSONDecodeError:
+            continue
+        hooks = s.get("hooks", {})
+        has_post = any("kyp-mem hook" in h.get("command", "") for h in hooks.get("PostToolUse", []))
+        has_stop = any("kyp-mem hook" in h.get("command", "") for h in hooks.get("Stop", []))
+        if has_post and has_stop:
+            print(f"  {G}✓{R} Auto-learning hooks installed ({label})")
+        elif has_post or has_stop:
+            print(f"  {Y}!{R} Partial hooks installed ({label}) — run: kyp-mem install-hooks")
+
+    # Session log
+    session_file = Path.home() / ".kyp-mem" / "sessions" / "current.jsonl"
+    if session_file.exists():
+        line_count = len(session_file.read_text().strip().split("\n"))
+        print(f"  {D}·{R} Active session log: {line_count} entries")
+
     # Binary
     kyp_bin = shutil.which("kyp-mem")
     if kyp_bin:

package/kyp_mem/hooks.py

@@ -0,0 +1,126 @@
+"""KYP-MEM session hooks — compile captured tool activity into vault notes."""
+
+import sys
+import json
+from datetime import datetime
+from pathlib import Path
+
+SESSION_DIR = Path.home() / ".kyp-mem" / "sessions"
+CURRENT_SESSION = SESSION_DIR / "current.jsonl"
+
+MIN_ACTIONS = 3
+
+
+def handle_stop():
+    if not CURRENT_SESSION.exists():
+        return
+
+    text = CURRENT_SESSION.read_text().strip()
+    if not text:
+        CURRENT_SESSION.unlink(missing_ok=True)
+        return
+
+    entries = []
+    for line in text.split("\n"):
+        try:
+            entries.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+
+    if not entries:
+        CURRENT_SESSION.unlink(missing_ok=True)
+        return
+
+    write_actions = [e for e in entries if e.get("action") in ("edit", "create", "command")]
+    if len(write_actions) < MIN_ACTIONS:
+        CURRENT_SESSION.unlink(missing_ok=True)
+        return
+
+    project_dir = entries[0].get("cwd", "unknown")
+    project_name = Path(project_dir).name
+    session_id = datetime.now().strftime("%Y-%m-%d_%H%M%S")
+
+    files_edited = set()
+    files_created = set()
+    commands = []
+    timeline = []
+
+    for e in entries:
+        ts_raw = e.get("ts", "")
+        ts = ts_raw[11:19] if len(ts_raw) >= 19 else ""
+        action = e.get("action", "")
+
+        if action == "edit":
+            fp = e.get("file", "")
+            files_edited.add(fp)
+            timeline.append(f"  {ts} — Edit `{Path(fp).name}`")
+        elif action == "create":
+            fp = e.get("file", "")
+            files_created.add(fp)
+            timeline.append(f"  {ts} — Write `{Path(fp).name}`")
+        elif action == "command":
+            cmd = e.get("command", "")
+            commands.append(cmd)
+            short = cmd[:80] + "..." if len(cmd) > 80 else cmd
+            timeline.append(f"  {ts} — `{short}`")
+
+    parts = [f"# Session {session_id}", ""]
+    parts.append(f"**Project:** `{project_dir}`")
+    parts.append(f"**Actions:** {len(entries)} total, {len(write_actions)} substantive")
+    parts.append("")
+
+    if files_edited:
+        parts.append("## Files Modified")
+        for f in sorted(files_edited):
+            parts.append(f"- `{f}`")
+        parts.append("")
+
+    if files_created:
+        parts.append("## Files Created")
+        for f in sorted(files_created):
+            parts.append(f"- `{f}`")
+        parts.append("")
+
+    if commands:
+        parts.append("## Commands Run")
+        for cmd in commands[:25]:
+            short = cmd[:120] + "..." if len(cmd) > 120 else cmd
+            parts.append(f"- `{short}`")
+        parts.append("")
+
+    if timeline:
+        parts.append("## Timeline")
+        for line in timeline[:40]:
+            parts.append(line)
+        if len(timeline) > 40:
+            parts.append(f"  ... and {len(timeline) - 40} more actions")
+
+    content = "\n".join(parts)
+    tags = ["session", "auto-captured", project_name]
+
+    from .config import get_vault_path
+    from .vault import Vault
+
+    vault = Vault(get_vault_path())
+    vault.write_note(f"Sessions/{session_id}.md", content, tags, {})
+
+    CURRENT_SESSION.unlink(missing_ok=True)
+
+
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] == "stop":
+        handle_stop()
+    else:
+        raw = sys.stdin.read().strip()
+        if not raw:
+            return
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            return
+        if "stop_reason" in data:
+            handle_stop()
+
+
+if __name__ == "__main__":
+    main()

package/kyp_mem/server.py

@@ -12,13 +12,18 @@ mcp = FastMCP("kyp-mem")
 
 @mcp.tool()
 def kyp_list(path: str = "") -> str:
-    """List notes and folders in the vault. Pass a folder path to list its contents, or empty for root."""
+    """List notes and folders in the vault. Shows inline tags for quick navigation. Pass a folder path or empty for root."""
     tree = vault.list_tree(path)
     lines = []
     for f in tree["folders"]:
         lines.append(f"  {f}/")
     for n in tree["notes"]:
-        lines.append(f"  {n}")
+        rel = f"{path}/{n}" if path else n
+        note = vault.index.notes.get(rel)
+        if note and note.tags:
+            lines.append(f"  {n}  [{', '.join(note.tags)}]")
+        else:
+            lines.append(f"  {n}")
     if not lines:
         lines.append("(empty vault)")
     header = f"Vault: {path or '/'}"
@@ -26,24 +31,46 @@ def kyp_list(path: str = "") -> str:
 
 
 @mcp.tool()
-def kyp_read(path: str) -> str:
-    """Read a note by path (e.g. 'Hedge Engine/Configuration.md'). Returns content + properties + backlinks + related notes."""
+def kyp_read(path: str, full: bool = False) -> str:
+    """Read a note. Returns brief summary by default (title, tags, preview, links). Set full=True for complete content."""
     note = vault.read(path)
     if not note:
         return f"Not found: {path}"
 
+    if not full:
+        parts = [f"# {note.title}"]
+        if note.tags:
+            parts.append(f"tags: {', '.join(note.tags)}")
+        if note.created:
+            parts.append(f"created: {note.created}")
+
+        lines = [l for l in note.content.strip().split("\n") if l.strip() and not l.startswith("# ")]
+        preview = "\n".join(lines[:6])
+        if len(lines) > 6:
+            preview += "\n..."
+        parts.append("")
+        parts.append(preview)
+
+        backlinks = vault.get_backlinks(path)
+        outlinks = note.links
+        if outlinks:
+            parts.append(f"\nlinks: {', '.join(f'[[{l}]]' for l in outlinks)}")
+        if backlinks:
+            parts.append(f"backlinks: {', '.join(f'[[{b.replace('.md', '')}]]' for b in backlinks)}")
+
+        return "\n".join(parts)
+
     parts = [f"# {note.title}", ""]
 
     if note.tags or note.properties or note.created:
-        parts.append("**Properties:**")
         if note.tags:
-            parts.append(f"  tags: {', '.join(note.tags)}")
+            parts.append(f"tags: {', '.join(note.tags)}")
         if note.created:
-            parts.append(f"  created: {note.created}")
+            parts.append(f"created: {note.created}")
         if note.updated:
-            parts.append(f"  updated: {note.updated}")
+            parts.append(f"updated: {note.updated}")
         for k, v in note.properties.items():
-            parts.append(f"  {k}: {v}")
+            parts.append(f"{k}: {v}")
         parts.append("")
 
     parts.append(note.content)