kyp-mem 0.4.0 → 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.3.0"
+__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/kyp_mem/server.py

@@ -11,6 +11,61 @@ vault = Vault(get_vault_path())
 mcp = FastMCP("kyp-mem")
 
 
+@mcp.tool()
+def ____kyp_instructions() -> str:
+    """## KYP-MEM — Know Your Project Memory
+
+YOU MUST FOLLOW THESE INSTRUCTIONS when kyp-mem tools are available.
+
+### AT SESSION START (MANDATORY)
+1. Identify the project you are working on from the user's working directory or question.
+2. Call `kyp_project_context(project)` to load the project's knowledge base, notes, and recent session summaries.
+3. If no project exists yet, call `kyp_project_context` anyway — if it returns empty, ask the user if you should create one.
+4. Use the returned context to ground yourself: understand architecture, known bugs, past decisions, and what was done in recent sessions. Do NOT ask the user questions that are already answered in the project context.
+
+### DURING WORK — WHEN TO SEARCH SESSIONS
+Call `kyp_session_search(query)` when:
+- You encounter a bug or error — search for it to see if it was investigated before.
+- You are about to make an architectural decision — check if a prior session already made this decision.
+- The user asks "did we already...", "what happened with...", "last time we..." — search sessions semantically.
+- You are unsure about project-specific behavior — sessions contain investigation logs.
+
+### DURING WORK — WHEN TO UPDATE KNOWLEDGE
+Call `kyp_write` to update the project's Knowledge.md when you:
+- Fix a bug → add it under ## Bugs > ### Fixed
+- Discover a new bug → add it under ## Bugs > ### Known
+- Make an architectural decision → add it under ## Key Decisions
+- Learn something important about the project → add it under ## Notes
+- Complete an improvement → move it from ## Improvements > ### Planned to ### Completed
+
+Also use `kyp_write` to create new project notes for substantial topics (API docs, setup guides, component deep-dives). Use [[wikilinks]] to connect notes.
+
+### DURING WORK — WHEN TO USE OTHER TOOLS
+- `kyp_search(query)` — keyword search across ALL notes (not just sessions). Use for finding specific content.
+- `kyp_read(path)` — read a specific note. Default is brief mode; use full=True for complete content.
+- `kyp_related(path)` — find notes connected by backlinks, tags, or folder proximity.
+- `kyp_tags(tag)` — browse by tag or list all tags.
+
+### SESSION CAPTURE
+Sessions are captured automatically by hooks — you do not need to create session notes manually. If the user explicitly asks to log a session, use `kyp_session_create`.
+
+### IMPORTANT RULES
+- NEVER hallucinate project details. If it's not in the knowledge base or sessions, say you don't know.
+- ALWAYS check knowledge base before making assumptions about project architecture.
+- Keep Knowledge.md updated as you work — it is the source of truth for future sessions.
+- Use [[wikilinks]] in notes to build the knowledge graph.
+- Tag notes consistently: use project name, topic tags, and type tags (bug, decision, guide, etc.).
+
+Call this tool to acknowledge these instructions. It returns a confirmation."""
+    projects = []
+    for path in vault.index.notes:
+        parts = path.split("/")
+        if len(parts) > 1:
+            projects.append(parts[0])
+    unique = sorted(set(projects))
+    return f"KYP-MEM active. Available projects: {', '.join(unique) if unique else '(none)'}. Call kyp_project_context(project) to load context."
+
+
 @mcp.tool()
 def kyp_list(path: str = "") -> str:
     """List notes and folders in the vault. Shows inline tags for quick navigation. Pass a folder path or empty for root."""
@@ -96,7 +151,7 @@ def kyp_read(path: str, full: bool = False) -> str:
 
 @mcp.tool()
 def kyp_write(path: str, content: str, tags: str = "", properties: str = "") -> str:
-    """Create or update a note. Path like 'Project/Note.md'. Tags: comma-separated. Properties: JSON string."""
+    """Create or update a note. Use this to persist knowledge: bug fixes, architectural decisions, setup guides, API contracts. Path like 'Project/Note.md'. Use [[wikilinks]] in content to connect notes. Tags: comma-separated. Properties: JSON string."""
     if not path.endswith(".md"):
         path += ".md"
 
@@ -194,6 +249,25 @@ def kyp_stats() -> str:
     )
 
 
+@mcp.tool()
+def kyp_session_search(query: str, project: str = None) -> str:
+    """Semantic search across past session logs using vector embeddings. Use this to recall: what was investigated, bugs encountered, decisions made, and next steps from prior sessions. Search before re-investigating known issues or making decisions that may have been made before."""
+    from .vector import get_session_memory
+    results = get_session_memory().search_sessions(query, project=project, n_results=5)
+    
+    if not results or not results.get("ids") or not results["ids"][0]:
+        return "No relevant past sessions found."
+    
+    lines = ["Semantic Session Search Results:", ""]
+    for i, path in enumerate(results["ids"][0]):
+        doc = results["documents"][0][i]
+        score = results["distances"][0][i]
+        lines.append(f"--- Session: {path} (Distance: {score:.2f}) ---")
+        lines.append(doc)
+        lines.append("")
+    return "\n".join(lines)
+
+
 @mcp.tool()
 def kyp_session_create(project: str, summary: str = "", investigated: str = "", learned: str = "", completed: str = "", next_steps: str = "") -> str:
     """Create a structured session note. Project is required. Sections accept markdown text."""
@@ -247,7 +321,7 @@ def kyp_sessions(project: str = "", limit: int = 10) -> str:
 
 @mcp.tool()
 def kyp_project_context(project: str) -> str:
-    """Get full project context: knowledge base + recent session summaries. Call this at session start to understand project history, avoid repeating past work, and prevent hallucination."""
+    """CALL THIS AT SESSION START. Returns the project's full context: Knowledge.md (ground truth), project notes, and recent session summaries. Use this to understand architecture, known bugs, past decisions, and what was done recently. This prevents hallucination and avoids repeating past work."""
     parts = []
 
     knowledge_path = f"{project}/Knowledge.md"