kyp-mem 0.4.1 → 0.4.2

package/README.md

@@ -1,140 +1,289 @@
 # KYP-MEM — Know Your Project Memory
 
-**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.
+**Persistent memory for AI coding agents.** Your AI agent forgets everything between sessions. KYP-MEM fixes that.
 
-## Install
+KYP-MEM is an MCP server that gives your AI agent a knowledge base and session memory. It remembers your architecture, past bugs, decisions, and what happened last session — so you never repeat yourself.
+
+---
+
+## How It Works
+
+KYP-MEM gives your agent two types of memory:
+
+### Knowledge Base — long-term project memory
+
+Structured markdown notes organized by project. Architecture docs, API references, known bugs, key decisions, setup guides. The agent reads these before doing any work and updates them as it learns.
 
-```bash
-npm install -g kyp-mem
 ```
+MyProject/
+├── Knowledge.md      # Architecture, bugs, decisions, notes
+├── API.md            # Endpoints and contracts
+├── Setup.md          # Environment setup guide
+└── Sessions/
+```
+
+### Session Memory — what happened each session
 
-Or run directly:
+Every coding session is automatically captured — files changed, commands run, prompts used. These notes are embedded into a vector database for semantic search, so the agent can find past work by meaning, not just keywords.
+
+```
+MyProject/Sessions/
+├── 2026-05-12_143022.md  # "Fixed auth bug, found rate limiter issue"
+├── 2026-05-12_091544.md  # "Investigated flaky tests — race condition"
+└── 2026-05-11_162301.md  # "Set up CI, decided on GitHub Actions"
+```
+
+### The Loop
+
+```
+Session Start
+  → Agent loads project knowledge + recent sessions
+  → Agent is grounded: knows architecture, past bugs, last session's next steps
+
+During Work
+  → Agent hits a bug → searches session memory → finds it was already investigated
+  → Agent makes a decision → updates Knowledge.md so future sessions know
+
+Session End
+  → Hooks auto-capture everything into a structured session note
+  → Note is embedded into the vector store for future semantic search
+```
+
+---
+
+## Install
 
 ```bash
-npx -y kyp-mem
+pip install kyp-mem
 ```
 
 ## Setup
 
 ```bash
-kyp-mem init            # Choose vault location
-kyp-mem setup-claude    # Auto-configure Claude Code MCP
-kyp-mem install-hooks   # Enable auto-learning from sessions
+kyp-mem init              # Choose where to store your vault
+kyp-mem setup-claude      # Register MCP server with Claude Code
+kyp-mem install-hooks     # Enable automatic session capture
 ```
 
-Restart Claude Code. Done — kyp-mem runs headlessly every session with 9 tools available.
+Restart Claude Code. KYP-MEM runs automatically with 14 tools available to the agent.
 
-## Auto-Learning
+### Quick Setup (one command)
+
+```bash
+claude mcp add -s user -e KYP_VAULT="$HOME/.kyp-mem/vault" kyp-mem -- kyp-mem serve
+```
 
-KYP-MEM can automatically capture what happens in every Claude Code session:
+### Enable for All Projects
 
 ```bash
+kyp-mem setup-claude --global
 kyp-mem install-hooks --global
 ```
 
-This installs two hooks:
-- **PostToolUse** — captures file edits, writes, and commands (pure Node, fast)
-- **Stop** — compiles session activity into a vault note under `Sessions/`
+---
+
+## What the Agent Does Automatically
+
+KYP-MEM embeds behavioral instructions directly into tool descriptions. The agent follows these rules without any user action:
+
+1. **Session start** — loads project knowledge + recent session history
+2. **Before investigating bugs** — searches session memory first to avoid duplicate work
+3. **Before making decisions** — checks if a prior session already decided this
+4. **After fixing or learning something** — updates Knowledge.md for future sessions
+5. **Never hallucinates** — if it's not in the knowledge base, it says so
+
+No prompting needed. The agent reads the tool descriptions and follows the protocol.
+
+---
+
+## Automatic Session Capture
+
+```bash
+kyp-mem install-hooks
+```
+
+Installs three Claude Code hooks:
+
+- **UserPromptSubmit** — captures every prompt you send to the agent
+- **PostToolUse** — captures file edits, writes, and shell commands in real-time
+- **Stop** — when the session ends, compiles all activity into a structured note
+
+Each session note looks like this:
+
+```markdown
+# Session 2026-05-12_143022
+
+**Project:** MyProject
+**Actions:** 15 total, 12 substantive
+
+## Summary
+Fixed auth bug, refactored token refresh logic.
+
+## PROMPTS
+### 1. [14:25:01]
+> fix the token refresh bug in auth.py
+
+### 2. [14:30:22]
+> also add retry logic for expired tokens
+
+## INVESTIGATED
+- grep for "token expired" across auth module
+- read OAuth provider docs
+
+## LEARNED
+- Refresh tokens expire after 30 days, not 90
+
+## COMPLETED
+- Fixed token refresh in auth.py
+- Added retry logic for expired tokens
+
+## NEXT STEPS
+- Add integration test for token refresh flow
+```
 
 Sessions with fewer than 3 substantive actions are automatically skipped.
 
+---
+
+## Semantic Search
+
+Session notes are embedded into a vector database (ChromaDB). This enables search by meaning:
+
+- Searching **"authentication failing"** finds sessions about "login bug" and "OAuth token expiry"
+- Searching **"deploy process"** finds sessions about "CI pipeline setup" and "release workflow"
+
+The agent doesn't need exact keywords — it finds semantically related past work.
+
+---
+
 ## Web UI
 
 ```bash
 kyp-mem ui
 ```
 
-Opens at `localhost:3333` with:
-- Quick switcher (`Cmd+O`) — fuzzy jump to any note
-- Full-text search (`Cmd+K`)
-- 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
+Opens at `localhost:3333` with two panels:
 
-## How It Works
+**Session Memory** — semantic search across all sessions, grouped by project with timestamps
 
-```
-┌─────────────┐          ┌─────────────┐          ┌──────────────┐
-│  Claude Code │──stdio──▶│  kyp-mem    │──read/──▶│  ~/.kyp-mem/ │
-│  (any AI)    │◀─────────│  MCP server │  write   │  vault/      │
-└─────────────┘          └─────────────┘          │    *.md files │
-                                                   └──────────────┘
-```
+**Knowledge Base** — file tree with folders, notes, tags. Full-text search, tag filtering, quick switcher (`Cmd+O`)
 
-- **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
+**Editor** — rendered markdown with `[[wikilink]]` navigation, inline editing
 
-## Commands
+**Graph** — knowledge graph showing connections between notes, backlinks, and related content
 
-| Command | What it does |
-|---------|-------------|
-| `kyp-mem init` | First-time setup — choose vault location |
-| `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 (14 total)
+
+### Agent Behavior
+
+| Tool | Purpose |
+|------|---------|
+| `____kyp_instructions` | Embeds behavioral rules the agent follows automatically |
+| `kyp_project_context` | Loads project knowledge + recent sessions at session start |
 
-## MCP Tools (9 tools)
+### Knowledge Base
 
-| Tool | Description |
-|------|-------------|
-| `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 |
+| Tool | Purpose |
+|------|---------|
+| `kyp_list` | Browse folders and notes |
+| `kyp_read` | Read a note (summary by default, `full=True` for complete) |
+| `kyp_write` | Create or update a note with tags and `[[wikilinks]]` |
 | `kyp_delete` | Delete a note |
 | `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, folder proximity |
+| `kyp_related` | Find related notes by links, tags, proximity |
 | `kyp_recent` | Recently modified notes |
 | `kyp_stats` | Vault statistics |
 
-## Note Format
+### Session Memory
+
+| Tool | Purpose |
+|------|---------|
+| `kyp_session_search` | Semantic search across all session logs |
+| `kyp_session_create` | Manually create a session note |
+| `kyp_sessions` | List sessions by project |
 
-```markdown
----
-tags: [project, trading, config]
-created: 2026-05-12
 ---
 
-# Configuration
+## Adding to Your Project
 
-Settings are in `HedgeConfig`. See [[Risk Management]] for safety checks.
-```
+Add a `CLAUDE.md` to any project root:
 
-`[[Wikilinks]]` are parsed, indexed, and resolved into navigable backlinks automatically.
+```markdown
+# Project Memory
+
+## Session Start (MANDATORY)
+Call `kyp_project_context("PROJECT_NAME")` at the start of every session to load:
+- Project knowledge base (architecture, bugs, decisions)
+- Recent session history (what was done, what's next)
+
+## During Work
+- Before investigating bugs: `kyp_session_search("error or symptom")`
+- Before making decisions: `kyp_session_search("topic")`
+- After fixing bugs: update Knowledge.md via `kyp_write`
+- After decisions: add to Key Decisions in Knowledge.md
+
+## Rules
+- Never hallucinate project details — check the knowledge base first.
+- Use [[wikilinks]] to connect related notes.
+- Sessions are captured automatically — no manual logging needed.
+```
 
-## Manual Claude Code Config
+A template is available at `templates/CLAUDE.md.template`.
 
-```bash
-claude mcp add -s user -e KYP_VAULT="$HOME/.kyp-mem/vault" kyp-mem -- npx -y kyp-mem serve
-```
+---
 
-## Architecture
+## Vault Structure
 
 ```
 ~/.kyp-mem/
-├── config.json       # vault path
-├── sessions/         # auto-learning session logs
+├── config.json           # Vault path configuration
+├── chroma/               # Vector database for semantic search
 └── vault/
-    ├── Project A/
-    │   ├── Architecture.md
-    │   └── Bugs.md
-    ├── Sessions/     # auto-captured session notes
+    ├── ProjectA/
+    │   ├── Knowledge.md  # Ground truth: architecture, bugs, decisions
+    │   ├── API.md
+    │   └── Sessions/
+    │       ├── 2026-05-12_143022.md
+    │       └── 2026-05-11_091544.md
+    ├── ProjectB/
+    │   ├── Knowledge.md
+    │   └── Sessions/
     └── ...
 ```
 
+Notes use YAML frontmatter for tags and `[[wikilinks]]` for cross-references:
+
+```markdown
+---
+tags: [trading, config]
+created: 2026-05-12
+---
+# Configuration
+Settings are in `HedgeConfig`. See [[Risk Management]] for limits.
+```
+
+---
+
+## CLI Commands
+
+| Command | What it does |
+|---------|-------------|
+| `kyp-mem init` | First-time setup — choose vault location |
+| `kyp-mem setup-claude` | Register MCP server with Claude Code |
+| `kyp-mem setup-claude --global` | Register globally (all projects) |
+| `kyp-mem install-hooks` | Enable automatic session capture |
+| `kyp-mem install-hooks --remove` | Remove session capture hooks |
+| `kyp-mem serve` | Start MCP server (stdio, used by the agent) |
+| `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 |
+
+---
+
 ## License
 
 MIT

package/kyp_mem/__init__.py

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

package/kyp_mem/cli.py

@@ -43,6 +43,12 @@ def main():
 
     subparsers.add_parser("doctor", help="Check installation and config health")
 
+    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("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")
+
     args = parser.parse_args()
 
     if args.vault:
@@ -66,6 +72,14 @@ def main():
         _run_install_hooks(global_config=args.global_config, remove=args.remove)
     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":
+            handle_post_tool_use()
+        elif args.hook_command == "user-prompt":
+            handle_user_prompt()
+        elif args.hook_command == "stop":
+            handle_stop()
     else:
         _print_banner()
         parser.print_help()
@@ -264,11 +278,17 @@ def _run_install_hooks(global_config: bool = False, remove: bool = False):
 
     hooks = settings.setdefault("hooks", {})
 
+    def _has_kyp_hook(entry):
+        for hook in entry.get("hooks", []):
+            if "kyp-mem hook" in hook.get("command", ""):
+                return True
+        return "kyp-mem hook" in entry.get("command", "")
+
     if remove:
         changed = False
-        for event in ("PostToolUse", "Stop"):
+        for event in ("PostToolUse", "UserPromptSubmit", "Stop"):
             if event in hooks:
-                hooks[event] = [h for h in hooks[event] if "kyp-mem hook" not in h.get("command", "")]
+                hooks[event] = [h for h in hooks[event] if not _has_kyp_hook(h)]
                 if not hooks[event]:
                     del hooks[event]
                 changed = True
@@ -282,20 +302,26 @@ def _run_install_hooks(global_config: bool = False, remove: bool = False):
         return
 
     post_tool_hooks = hooks.setdefault("PostToolUse", [])
+    prompt_hooks = hooks.setdefault("UserPromptSubmit", [])
     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 = [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)]
 
     post_tool_hooks.append({
         "matcher": "Edit|Write|Bash",
         "hooks": [{"type": "command", "command": f"{mcp_command} hook post-tool-use"}],
     })
+    prompt_hooks.append({
+        "hooks": [{"type": "command", "command": f"{mcp_command} hook user-prompt"}],
+    })
     stop_hooks.append({
         "hooks": [{"type": "command", "command": f"{mcp_command} hook stop"}],
     })
 
     hooks["PostToolUse"] = post_tool_hooks
+    hooks["UserPromptSubmit"] = prompt_hooks
     hooks["Stop"] = stop_hooks
 
     settings_path.write_text(json.dumps(settings, indent=2) + "\n")

package/kyp_mem/hooks.py

@@ -1,5 +1,6 @@
 """KYP-MEM session hooks — compile captured tool activity into vault notes."""
 
+import os
 import sys
 import json
 from datetime import datetime
@@ -11,6 +12,65 @@ CURRENT_SESSION = SESSION_DIR / "current.jsonl"
 MIN_ACTIONS = 3
 
 
+def handle_user_prompt():
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return
+
+    prompt = data.get("prompt", "").strip()
+    if not prompt:
+        return
+
+    entry = {
+        "ts": datetime.now().isoformat(),
+        "cwd": os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()),
+        "action": "prompt",
+        "prompt": prompt,
+    }
+
+    SESSION_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CURRENT_SESSION, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def handle_post_tool_use():
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return
+
+    tool_name = data.get("tool_name", "")
+    tool_input = data.get("tool_input", {})
+
+    entry = {"ts": datetime.now().isoformat()}
+
+    cwd = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    entry["cwd"] = cwd
+
+    if tool_name == "Edit":
+        entry["action"] = "edit"
+        entry["file"] = tool_input.get("file_path", "")
+    elif tool_name == "Write":
+        entry["action"] = "create"
+        entry["file"] = tool_input.get("file_path", "")
+    elif tool_name == "Bash":
+        entry["action"] = "command"
+        entry["command"] = tool_input.get("command", "")
+    else:
+        return
+
+    SESSION_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CURRENT_SESSION, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
 def handle_stop():
     if not CURRENT_SESSION.exists():
         return
@@ -43,6 +103,7 @@ def handle_stop():
     files_edited = set()
     files_created = set()
     commands = []
+    prompts = []
     timeline = []
 
     for e in entries:
@@ -50,7 +111,10 @@ def handle_stop():
         ts = ts_raw[11:19] if len(ts_raw) >= 19 else ""
         action = e.get("action", "")
 
-        if action == "edit":
+        if action == "prompt":
+            prompts.append({"ts": ts, "text": e.get("prompt", "")})
+            timeline.append(f"  {ts} — Prompt: {e.get('prompt', '')[:60]}...")
+        elif action == "edit":
             fp = e.get("file", "")
             files_edited.add(fp)
             timeline.append(f"  {ts} — Edit `{Path(fp).name}`")
@@ -88,6 +152,14 @@ def handle_stop():
     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_cmds:
         for cmd in investigated_cmds[:15]:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kyp-mem",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Know Your Project — Persistent knowledge base for AI agents. MCP-powered with wikilinks, backlinks, auto-learning, and neon web UI.",
   "bin": {
     "kyp-mem": "bin/cli.mjs"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kyp-mem"
-version = "0.4.1"
+version = "0.4.2"
 description = "Know Your Project — Persistent knowledge base for AI agents. MCP-powered with wikilinks, backlinks, auto-learning, and neon web UI."
 readme = "README.md"
 license = {text = "MIT"}