kyp-mem 0.4.3 → 0.5.0

package/kyp_mem/cli.py

@@ -43,8 +43,13 @@ def main():
 
     subparsers.add_parser("doctor", help="Check installation and config health")
 
+    cfg_parser = subparsers.add_parser("config", help="Get or set configuration values")
+    cfg_parser.add_argument("key", nargs="?", help="Config key (e.g. session_model)")
+    cfg_parser.add_argument("value", nargs="?", help="Value to set")
+
     hook_parser = subparsers.add_parser("hook", help="Handle Claude Code hook events (internal)")
     hook_sub = hook_parser.add_subparsers(dest="hook_command")
+    hook_sub.add_parser("session-start", help="Inject project context at session start")
     hook_sub.add_parser("post-tool-use", help="Capture tool activity to session log")
     hook_sub.add_parser("user-prompt", help="Capture user prompt to session log")
     hook_sub.add_parser("stop", help="Compile session into vault note")
@@ -70,11 +75,15 @@ def main():
         _run_tree()
     elif args.command == "install-hooks":
         _run_install_hooks(global_config=args.global_config, remove=args.remove)
+    elif args.command == "config":
+        _run_config(args.key, args.value)
     elif args.command == "doctor":
         _run_doctor()
     elif args.command == "hook":
-        from .hooks import handle_post_tool_use, handle_user_prompt, handle_stop
-        if args.hook_command == "post-tool-use":
+        from .hooks import handle_session_start, handle_post_tool_use, handle_user_prompt, handle_stop
+        if args.hook_command == "session-start":
+            handle_session_start()
+        elif args.hook_command == "post-tool-use":
             handle_post_tool_use()
         elif args.hook_command == "user-prompt":
             handle_user_prompt()
@@ -286,7 +295,7 @@ def _run_install_hooks(global_config: bool = False, remove: bool = False):
 
     if remove:
         changed = False
-        for event in ("PostToolUse", "UserPromptSubmit", "Stop"):
+        for event in ("SessionStart", "PostToolUse", "UserPromptSubmit", "Stop"):
             if event in hooks:
                 hooks[event] = [h for h in hooks[event] if not _has_kyp_hook(h)]
                 if not hooks[event]:
@@ -301,14 +310,19 @@ def _run_install_hooks(global_config: bool = False, remove: bool = False):
         print()
         return
 
+    session_start_hooks = hooks.setdefault("SessionStart", [])
     post_tool_hooks = hooks.setdefault("PostToolUse", [])
     prompt_hooks = hooks.setdefault("UserPromptSubmit", [])
     stop_hooks = hooks.setdefault("Stop", [])
 
+    session_start_hooks = [h for h in session_start_hooks if not _has_kyp_hook(h)]
     post_tool_hooks = [h for h in post_tool_hooks if not _has_kyp_hook(h)]
     prompt_hooks = [h for h in prompt_hooks if not _has_kyp_hook(h)]
     stop_hooks = [h for h in stop_hooks if not _has_kyp_hook(h)]
 
+    session_start_hooks.append({
+        "hooks": [{"type": "command", "command": f"{mcp_command} hook session-start"}],
+    })
     post_tool_hooks.append({
         "matcher": "Edit|Write|Read|Bash",
         "hooks": [{"type": "command", "command": f"{mcp_command} hook post-tool-use"}],
@@ -320,6 +334,7 @@ def _run_install_hooks(global_config: bool = False, remove: bool = False):
         "hooks": [{"type": "command", "command": f"{mcp_command} hook stop"}],
     })
 
+    hooks["SessionStart"] = session_start_hooks
     hooks["PostToolUse"] = post_tool_hooks
     hooks["UserPromptSubmit"] = prompt_hooks
     hooks["Stop"] = stop_hooks
@@ -342,6 +357,32 @@ def _run_install_hooks(global_config: bool = False, remove: bool = False):
     print()
 
 
+def _run_config(key, value):
+    from .config import load_config, save_config
+
+    config = load_config()
+
+    if key is None:
+        print(f"\n  {C}KYP-MEM{R} — Configuration\n")
+        for k, v in sorted(config.items()):
+            print(f"  {k}: {G}{v}{R}")
+        print(f"\n  {D}Configurable keys:{R}")
+        print(f"  {D}  vault_path      — Path to vault directory{R}")
+        print(f"  {D}  session_model   — Claude model for session summarization{R}")
+        print(f"  {D}                    (default: claude-haiku-4-5-20251001){R}")
+        print()
+        return
+
+    if value is None:
+        current = config.get(key, f"{Y}(not set){R}")
+        print(f"  {key}: {G}{current}{R}")
+        return
+
+    config[key] = value
+    save_config(config)
+    print(f"  {G}✓{R} {key} = {value}")
+
+
 def _run_stats():
     from .config import get_vault_path
     from .vault import Vault

package/kyp_mem/config.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 CONFIG_DIR = Path.home() / ".kyp-mem"
 CONFIG_FILE = CONFIG_DIR / "config.json"
+STATS_FILE = CONFIG_DIR / "token_stats.json"
 DEFAULT_VAULT = str(CONFIG_DIR / "vault")
 
 
@@ -29,3 +30,8 @@ def get_vault_path() -> str:
         return env
     config = load_config()
     return config.get("vault_path", DEFAULT_VAULT)
+
+
+def get_session_model() -> str:
+    config = load_config()
+    return config.get("session_model", "claude-haiku-4-5-20251001")

package/kyp_mem/hooks.py

@@ -10,6 +10,147 @@ SESSION_DIR = Path.home() / ".kyp-mem" / "sessions"
 CURRENT_SESSION = SESSION_DIR / "current.jsonl"
 
 MIN_ACTIONS = 3
+CHARS_PER_TOKEN = 4
+
+COMMAND_OUTPUT_ESTIMATES = {
+    "search": 2000,
+    "explore": 1000,
+    "read_cmd": 3000,
+    "git_inspect": 3000,
+    "test": 2000,
+    "build": 500,
+    "run": 200,
+    "git_write": 200,
+    "api_test": 1000,
+    "other": 300,
+}
+
+
+def _load_token_stats():
+    from .config import STATS_FILE
+    if STATS_FILE.exists():
+        try:
+            return json.loads(STATS_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {"sessions": [], "injections": []}
+
+
+def _save_token_stats(stats):
+    from .config import STATS_FILE
+    STATS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    STATS_FILE.write_text(json.dumps(stats, indent=2) + "\n")
+
+
+def _record_session_tokens(session_id, project, exploration_tokens,
+                           files_read_count, files_read_chars,
+                           commands_run, commands_chars,
+                           files_edited, files_created):
+    stats = _load_token_stats()
+    stats["sessions"].append({
+        "id": session_id,
+        "project": project,
+        "ts": datetime.now().isoformat(),
+        "exploration_tokens": exploration_tokens,
+        "files_read": files_read_count,
+        "files_read_chars": files_read_chars,
+        "commands_run": commands_run,
+        "commands_chars": commands_chars,
+        "files_edited": files_edited,
+        "files_created": files_created,
+    })
+    _save_token_stats(stats)
+
+
+def _record_injection(project, chars):
+    stats = _load_token_stats()
+    stats["injections"].append({
+        "ts": datetime.now().isoformat(),
+        "project": project,
+        "chars": chars,
+        "tokens": chars // CHARS_PER_TOKEN,
+    })
+    _save_token_stats(stats)
+
+
+def handle_session_start():
+    """Inject project context into the conversation at session start."""
+    sys.stdin.read()
+
+    cwd = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    project_name = Path(cwd).name
+
+    try:
+        from .config import get_vault_path
+        from .vault import Vault
+
+        vault = Vault(get_vault_path())
+
+        project_notes = [p for p in vault.index.notes if p.startswith(f"{project_name}/")]
+        if not project_notes:
+            return
+
+        parts = [f"# [kyp-mem] {project_name} — Project Context"]
+        parts.append(f"Vault: {get_vault_path()}")
+        parts.append("")
+
+        knowledge_path = f"{project_name}/Knowledge.md"
+        knowledge = vault.read(knowledge_path)
+        if knowledge:
+            parts.append("## Knowledge")
+            content = knowledge.content
+            timeline_idx = content.find("## Timeline")
+            if timeline_idx > 0:
+                content = content[:timeline_idx].strip()
+            if len(content) > 2000:
+                parts.append(content[:2000] + "\n...")
+            else:
+                parts.append(content)
+            parts.append("")
+
+        other_notes = sorted(
+            p for p in project_notes
+            if "/Sessions/" not in p and p != knowledge_path
+        )
+        if other_notes:
+            parts.append("## Project Notes")
+            for p in other_notes:
+                note = vault.index.notes.get(p)
+                title = note.title if note else p
+                tags = f" [{', '.join(note.tags)}]" if note and note.tags else ""
+                parts.append(f"- {title} ({p}){tags}")
+            parts.append("")
+
+        sessions = sorted(
+            (p for p in project_notes if "/Sessions/" in p),
+            reverse=True,
+        )[:3]
+        if sessions:
+            parts.append(f"## Recent Sessions (last {len(sessions)})")
+            for sp in sessions:
+                note = vault.read(sp)
+                if not note:
+                    continue
+                parts.append(f"### {note.title}")
+                content = note.content
+                timeline_idx = content.find("## Timeline")
+                if timeline_idx > 0:
+                    content = content[:timeline_idx].strip()
+                if len(content) > 300:
+                    content = content[:300] + "..."
+                parts.append(content)
+                parts.append("")
+
+        parts.append("Use `kyp_project_context` for full details. Use `kyp_session_search` to search past sessions.")
+
+        output = "\n".join(parts)
+        try:
+            _record_injection(project_name, len(output))
+        except Exception:
+            pass
+        print(output)
+    except Exception:
+        pass
 
 
 def handle_user_prompt():
@@ -54,6 +195,10 @@ def handle_post_tool_use():
     cwd = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
     entry["cwd"] = cwd
 
+    # Measure response size for token economics
+    tool_response = data.get("tool_response", "")
+    response_chars = len(str(tool_response)) if tool_response else 0
+
     if tool_name == "Edit":
         entry["action"] = "edit"
         entry["file"] = tool_input.get("file_path", "")
@@ -63,9 +208,16 @@ def handle_post_tool_use():
     elif tool_name == "Read":
         entry["action"] = "read"
         entry["file"] = tool_input.get("file_path", "")
+        if response_chars == 0:
+            try:
+                response_chars = Path(tool_input.get("file_path", "")).stat().st_size
+            except OSError:
+                pass
+        entry["response_chars"] = response_chars
     elif tool_name == "Bash":
         entry["action"] = "command"
         entry["command"] = tool_input.get("command", "")
+        entry["response_chars"] = response_chars
     else:
         return
 
@@ -265,6 +417,58 @@ def _build_next_steps(files_edited, files_created, commands_classified):
     return items
 
 
+def _summarize_with_claude(raw_note, project_name):
+    """Use Claude to rewrite session sections in plain, human-readable language."""
+    try:
+        from .config import get_session_model
+        import anthropic
+
+        model = get_session_model()
+        client = anthropic.Anthropic()
+
+        prompt = f"""Summarize this coding session for "{project_name}" in plain English. A future AI agent will read this to understand what happened — write for that audience.
+
+You have: user prompts (what was asked), a timeline of file edits/reads/commands (what happened), and raw section data. Synthesize these into a coherent narrative.
+
+Rules:
+- Summary: 2-3 sentences. State the objective (from prompts), what was done, and the outcome. Be specific: "Fixed navigation bug where clicking sessions broke the back button" not "Modified files and ran commands."
+- INVESTIGATED: What was explored and WHY. "Examined the session hook pipeline to understand why summaries were empty" not "Searched for `session-view`". Max 4 bullets.
+- LEARNED: Insights or discoveries. "The config CLI command was defined but never wired to the dispatcher" not "Investigated and modified: `cli.py`". Max 4 bullets.
+- COMPLETED: Concrete deliverables. "Added AI-powered session summarization using Claude Haiku" not "Modified `hooks.py`". Max 5 bullets.
+- NEXT STEPS: What should happen next session. Infer from context — unfinished work, unfixed bugs, natural follow-ups. Max 3 bullets.
+
+NEVER include raw grep patterns, CSS class names, file paths, or command output. Write like you're telling a teammate what you did today.
+
+Return ONLY this format (no preamble):
+
+## Summary
+<text>
+
+## INVESTIGATED
+- <item>
+
+## LEARNED
+- <item>
+
+## COMPLETED
+- <item>
+
+## NEXT STEPS
+- <item>
+
+Raw session data:
+{raw_note}"""
+
+        response = client.messages.create(
+            model=model,
+            max_tokens=1024,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return response.content[0].text.strip()
+    except Exception:
+        return None
+
+
 def handle_stop():
     if not CURRENT_SESSION.exists():
         return
@@ -342,49 +546,130 @@ def handle_stop():
     completed = _build_completed(files_edited, files_created, commands_classified, project_dir)
     next_steps = _build_next_steps(files_edited, files_created, commands_classified)
 
-    parts = [f"# Session {session_id}", ""]
-    parts.append(f"**Project:** `{project_dir}`")
-    parts.append(f"**Actions:** {len(entries)} total, {len(write_actions)} substantive")
-    parts.append("")
-
-    parts.append("## Summary")
-    parts.append(", ".join(summary_items) + f" in `{project_name}`." if summary_items else "")
-    parts.append("")
+    # Build raw note for Claude summarization
+    raw_parts = []
+    raw_parts.append("## Summary")
+    raw_parts.append(", ".join(summary_items) + f" in `{project_name}`." if summary_items else "")
+    raw_parts.append("")
+    raw_parts.append("## INVESTIGATED")
+    if investigated:
+        raw_parts.extend(investigated)
+    raw_parts.append("")
+    raw_parts.append("## LEARNED")
+    if learned:
+        raw_parts.extend(learned)
+    raw_parts.append("")
+    raw_parts.append("## COMPLETED")
+    if completed:
+        raw_parts.extend(completed)
+    raw_parts.append("")
+    raw_parts.append("## NEXT STEPS")
+    if next_steps:
+        raw_parts.extend(next_steps)
 
-    parts.append("## PROMPTS")
+    # Prompts go FIRST — they define the session's objective
     if prompts:
-        for i, p in enumerate(prompts, 1):
-            parts.append(f"### {i}. [{p['ts']}]")
-            parts.append(f"> {p['text']}")
-            parts.append("")
-    parts.append("")
+        raw_parts.insert(0, "## USER PROMPTS (what was asked)")
+        for i, p in enumerate(prompts):
+            raw_parts.insert(i + 1, f"- [{p['ts']}] {p['text'][:300]}")
+        raw_parts.insert(len(prompts) + 1, "")
 
-    parts.append("## INVESTIGATED")
-    if investigated:
-        parts.extend(investigated)
-    parts.append("")
+    # Full timeline gives Claude the narrative arc
+    if timeline:
+        raw_parts.append("")
+        raw_parts.append("## TIMELINE (what happened, chronological)")
+        for line in timeline[:50]:
+            raw_parts.append(line)
 
-    parts.append("## LEARNED")
-    if learned:
-        parts.extend(learned)
-    parts.append("")
+    raw_note = "\n".join(raw_parts)
 
-    parts.append("## COMPLETED")
-    if completed:
-        parts.extend(completed)
-    parts.append("")
+    # Compute exploration tokens from captured response sizes
+    files_read_chars = 0
+    commands_chars = 0
+    files_read_count = len(files_read)
+    commands_run_count = len(commands)
 
-    parts.append("## NEXT STEPS")
-    if next_steps:
-        parts.extend(next_steps)
+    for e in entries:
+        rc = e.get("response_chars", 0)
+        if e.get("action") == "read":
+            if rc > 0:
+                files_read_chars += rc
+            else:
+                try:
+                    files_read_chars += Path(e.get("file", "")).stat().st_size
+                except OSError:
+                    pass
+        elif e.get("action") == "command":
+            if rc > 0:
+                commands_chars += rc
+            else:
+                cls, _ = _classify_command(e.get("command", ""))
+                commands_chars += COMMAND_OUTPUT_ESTIMATES.get(cls, 300)
+
+    exploration_chars = files_read_chars + commands_chars
+    exploration_tokens = exploration_chars // CHARS_PER_TOKEN
+
+    try:
+        _record_session_tokens(
+            session_id, project_name, exploration_tokens,
+            files_read_count, files_read_chars,
+            commands_run_count, commands_chars,
+            len(files_edited), len(files_created),
+        )
+    except Exception:
+        pass
+
+    # Try Claude summarization, fall back to raw sections
+    summarized = _summarize_with_claude(raw_note, project_name)
+
+    parts = [f"# Session {session_id}", ""]
+    parts.append(f"**Project:** `{project_dir}`")
+    parts.append(f"**Actions:** {len(entries)} total, {len(write_actions)} substantive")
+    parts.append(f"**Exploration:** ~{exploration_tokens:,} tokens ({files_read_count} reads, {commands_run_count} commands)")
     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")
+    if summarized:
+        # Insert prompts section before the Claude-rewritten sections
+        parts.append("## PROMPTS")
+        if prompts:
+            for i, p in enumerate(prompts, 1):
+                parts.append(f"### {i}. [{p['ts']}]")
+                parts.append(f"> {p['text']}")
+                parts.append("")
+        parts.append("")
+        parts.append(summarized)
+    else:
+        parts.append("## Summary")
+        parts.append(", ".join(summary_items) + f" in `{project_name}`." if summary_items else "")
+        parts.append("")
+
+        parts.append("## PROMPTS")
+        if prompts:
+            for i, p in enumerate(prompts, 1):
+                parts.append(f"### {i}. [{p['ts']}]")
+                parts.append(f"> {p['text']}")
+                parts.append("")
+        parts.append("")
+
+        parts.append("## INVESTIGATED")
+        if investigated:
+            parts.extend(investigated)
+        parts.append("")
+
+        parts.append("## LEARNED")
+        if learned:
+            parts.extend(learned)
+        parts.append("")
+
+        parts.append("## COMPLETED")
+        if completed:
+            parts.extend(completed)
+        parts.append("")
+
+        parts.append("## NEXT STEPS")
+        if next_steps:
+            parts.extend(next_steps)
+        parts.append("")
 
     content = "\n".join(parts)
     tags = ["session", "auto-captured", project_name]

package/kyp_mem/server.py

@@ -237,16 +237,39 @@ def kyp_recent(limit: int = 10) -> str:
 
 @mcp.tool()
 def kyp_stats() -> str:
-    """Get vault statistics — note count, folders, tags, links."""
+    """Get vault statistics — note count, folders, tags, links, and token economics (exploration cost vs memory injection cost)."""
     s = vault.get_stats()
-    return (
-        f"Vault stats:\n"
-        f"  Notes: {s['notes']}\n"
-        f"  Folders: {s['folders']}\n"
-        f"  Tags: {s['tags']}\n"
-        f"  Links: {s['links']}\n"
-        f"  Backlinks: {s['backlinks']}"
-    )
+    lines = [
+        "Vault stats:",
+        f"  Notes: {s['notes']}",
+        f"  Folders: {s['folders']}",
+        f"  Tags: {s['tags']}",
+        f"  Links: {s['links']}",
+        f"  Backlinks: {s['backlinks']}",
+    ]
+
+    try:
+        from .config import STATS_FILE
+        raw = json.loads(STATS_FILE.read_text()) if STATS_FILE.exists() else {}
+        sessions = raw.get("sessions", [])
+        injections = raw.get("injections", [])
+        if sessions:
+            total_exploration = sum(s.get("exploration_tokens", 0) for s in sessions)
+            avg_exploration = total_exploration // len(sessions)
+            latest_inj = injections[-1].get("tokens", 0) if injections else 0
+            lines.append("")
+            lines.append("Token economics:")
+            lines.append(f"  Total exploration: ~{total_exploration:,}t across {len(sessions)} sessions")
+            lines.append(f"  Avg per session: ~{avg_exploration:,}t (cold-start cost)")
+            lines.append(f"  Memory injection: ~{latest_inj:,}t (session start)")
+            if latest_inj > 0 and avg_exploration > 0:
+                ratio = round(avg_exploration / latest_inj, 1)
+                pct = round((1 - latest_inj / avg_exploration) * 100, 1)
+                lines.append(f"  Compression: {ratio}x — {pct}% smaller than re-exploring")
+    except Exception:
+        pass
+
+    return "\n".join(lines)
 
 
 @mcp.tool()