kyp-mem 0.2.1 → 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,95 +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` | Auto-configure Claude Code MCP settings |
+| `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`:
-
-```json
-{
-  "mcpServers": {
-    "kyp-mem": {
-      "command": "npx",
-      "args": ["-y", "kyp-mem", "serve"],
-      "env": {
-        "KYP_VAULT": "~/.kyp-mem/vault"
-      }
-    }
-  }
-}
+```bash
+claude mcp add -s user -e KYP_VAULT="$HOME/.kyp-mem/vault" kyp-mem -- npx -y kyp-mem serve
 ```
 
-Add to `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project).
-
 ## 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

@@ -4,6 +4,7 @@ import os
 import json
 import shutil
 import argparse
+import subprocess
 from pathlib import Path
 
 C = "\033[36m"  # cyan
@@ -35,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()
@@ -56,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:
@@ -107,28 +115,112 @@ def _run_setup_claude(global_config: bool = False):
     from .config import get_vault_path
 
     vault_path = get_vault_path()
+    mcp_command, mcp_args = _get_mcp_command()
+    claude_scope = "user" if global_config else "local"
+    scope_label = "global user" if global_config else "local project"
+
+    registered, detail = _register_with_claude_mcp(
+        claude_scope,
+        mcp_command,
+        mcp_args,
+        vault_path,
+    )
+
+    print()
+    print(f"  {C}KYP-MEM{R} — Claude Code Setup")
+    print()
+    if registered:
+        print(f"  {G}✓{R} MCP server registered with Claude Code ({scope_label})")
+    else:
+        settings_path = _write_legacy_claude_settings(global_config, mcp_command, mcp_args, vault_path)
+        print(f"  {Y}✗{R} Could not register with Claude Code's MCP manager")
+        print(f"  {D}  Reason:  {detail}{R}")
+        print(f"  {Y}!{R} Wrote legacy settings as a fallback")
+        print(f"  {D}  File:    {settings_path}{R}")
+    print(f"  {D}  Command: {mcp_command} {' '.join(mcp_args)}{R}")
+    print(f"  {D}  Vault:   {vault_path}{R}")
+    print()
+    print(f"  {C}Done!{R} Restart Claude Code and kyp-mem will run automatically.")
+    print(f"  Claude gets these tools: kyp_list, kyp_read, kyp_write, kyp_delete,")
+    print(f"  kyp_search, kyp_tags, kyp_related, kyp_recent, kyp_stats")
+    print()
+    print(f"  {D}To open the web UI anytime:{R} {Y}kyp-mem ui{R}")
+    print()
+
+
+def _get_mcp_command() -> tuple[str, list[str]]:
     kyp_mem_bin = shutil.which("kyp-mem")
     npx_bin = shutil.which("npx")
 
     if kyp_mem_bin and "_npx" not in Path(kyp_mem_bin).parts:
-        mcp_command = kyp_mem_bin
-        mcp_args = ["serve"]
-    elif npx_bin:
-        mcp_command = npx_bin
-        mcp_args = ["-y", "kyp-mem", "serve"]
-    else:
-        print(f"  {Y}Warning:{R} 'kyp-mem' not found in PATH.")
-        print(f"  {D}Make sure you installed with: npm install -g kyp-mem{R}")
-        print()
-        mcp_command = "kyp-mem"
-        mcp_args = ["serve"]
+        return kyp_mem_bin, ["serve"]
+    if npx_bin:
+        return npx_bin, ["-y", "kyp-mem", "serve"]
 
+    print(f"  {Y}Warning:{R} 'kyp-mem' not found in PATH.")
+    print(f"  {D}Make sure you installed with: npm install -g kyp-mem{R}")
+    print()
+    return "kyp-mem", ["serve"]
+
+
+def _register_with_claude_mcp(
+    scope: str,
+    mcp_command: str,
+    mcp_args: list[str],
+    vault_path: str,
+) -> tuple[bool, str]:
+    claude_bin = shutil.which("claude")
+    if not claude_bin:
+        return False, "'claude' CLI not found in PATH"
+
+    server_config = {
+        "type": "stdio",
+        "command": mcp_command,
+        "args": mcp_args,
+        "env": {
+            "KYP_VAULT": vault_path,
+        },
+    }
+
+    # Make setup idempotent when the user reruns it with a new vault or binary.
+    subprocess.run(
+        [claude_bin, "mcp", "remove", "-s", scope, "kyp-mem"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        text=True,
+    )
+
+    result = subprocess.run(
+        [
+            claude_bin,
+            "mcp",
+            "add-json",
+            "-s",
+            scope,
+            "kyp-mem",
+            json.dumps(server_config),
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode == 0:
+        return True, result.stdout.strip()
+
+    detail = (result.stderr or result.stdout or "unknown error").strip()
+    return False, detail
+
+
+def _write_legacy_claude_settings(
+    global_config: bool,
+    mcp_command: str,
+    mcp_args: list[str],
+    vault_path: str,
+) -> Path:
     if global_config:
         settings_path = Path.home() / ".claude" / "settings.json"
-        scope = "global"
     else:
         settings_path = Path.cwd() / ".claude" / "settings.json"
-        scope = "project"
 
     settings_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -140,7 +232,6 @@ def _run_setup_claude(global_config: bool = False):
             settings = {}
 
     mcp_servers = settings.setdefault("mcpServers", {})
-
     mcp_servers["kyp-mem"] = {
         "command": mcp_command,
         "args": mcp_args,
@@ -149,21 +240,79 @@ def _run_setup_claude(global_config: bool = False):
         },
     }
 
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+    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} — Claude Code Setup")
+    print(f"  {C}KYP-MEM{R} — Auto-Learning Hooks")
     print()
-    print(f"  {G}✓{R} MCP server added to {scope} settings")
-    print(f"  {D}  File:    {settings_path}{R}")
-    print(f"  {D}  Command: {mcp_command} {' '.join(mcp_args)}{R}")
-    print(f"  {D}  Vault:   {vault_path}{R}")
+    print(f"  {G}✓{R} Hooks installed ({scope_label})")
+    print(f"  {D}  File: {settings_path}{R}")
     print()
-    print(f"  {C}Done!{R} Restart Claude Code and kyp-mem will run automatically.")
-    print(f"  Claude gets these tools: kyp_list, kyp_read, kyp_write, kyp_delete,")
-    print(f"  kyp_search, kyp_tags, kyp_related, kyp_recent, kyp_stats")
+    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"  {D}To open the web UI anytime:{R} {Y}kyp-mem ui{R}")
+    print(f"  {C}Done!{R} Restart Claude Code. Sessions will auto-save to your vault.")
     print()
 
 
@@ -212,22 +361,59 @@ def _run_doctor():
     else:
         print(f"  {Y}✗{R} Vault not found: {vault_path}")
 
-    # Claude Code config
-    for label, path in [
+    # Claude Code MCP registration
+    claude_bin = shutil.which("claude")
+    if claude_bin:
+        result = subprocess.run(
+            [claude_bin, "mcp", "get", "kyp-mem"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0 and "Status: ✓ Connected" in result.stdout:
+            print(f"  {G}✓{R} Claude Code MCP: kyp-mem connected")
+        elif result.returncode == 0:
+            print(f"  {Y}✗{R} Claude Code MCP: kyp-mem registered but not connected")
+        else:
+            print(f"  {Y}✗{R} Claude Code MCP: kyp-mem not active")
+    else:
+        print(f"  {Y}✗{R} Claude Code CLI not found in PATH")
+
+    legacy_paths = [
         ("project", Path.cwd() / ".claude" / "settings.json"),
         ("global", Path.home() / ".claude" / "settings.json"),
-    ]:
-        if path.exists():
-            try:
-                s = json.loads(path.read_text())
-                if "kyp-mem" in s.get("mcpServers", {}):
-                    print(f"  {G}✓{R} Claude Code ({label}): kyp-mem configured")
-                else:
-                    print(f"  {D}·{R} Claude Code ({label}): exists but kyp-mem not configured")
-            except json.JSONDecodeError:
-                print(f"  {Y}✗{R} Claude Code ({label}): invalid JSON")
-        else:
-            print(f"  {D}·{R} Claude Code ({label}): no settings file")
+    ]
+    for label, path in legacy_paths:
+        if not path.exists():
+            continue
+        try:
+            s = json.loads(path.read_text())
+        except json.JSONDecodeError:
+            print(f"  {Y}✗{R} Legacy Claude settings ({label}): invalid JSON")
+            continue
+        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")