kyp-mem 0.4.1 → 0.4.3

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/bin/cli.mjs

@@ -60,6 +60,23 @@ if (args[0] === "hook") {
   await new Promise((r) => process.stdin.on("end", r));
   const raw = Buffer.concat(chunks).toString();
 
+  if (hookType === "user-prompt") {
+    try {
+      const data = JSON.parse(raw);
+      const prompt = (data.prompt || "").trim();
+      if (!prompt) process.exit(0);
+      const entry = {
+        ts: new Date().toISOString(),
+        cwd: process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+        action: "prompt",
+        prompt,
+      };
+      mkdirSync(sessionDir, { recursive: true });
+      appendFileSync(sessionFile, JSON.stringify(entry) + "\n");
+    } catch (_) {}
+    process.exit(0);
+  }
+
   if (hookType === "post-tool-use") {
     try {
       const data = JSON.parse(raw);
@@ -72,6 +89,9 @@ if (args[0] === "hook") {
       if (tool === "Edit" || tool === "Write") {
         entry.file = input.file_path || "";
         entry.action = tool === "Edit" ? "edit" : "create";
+      } else if (tool === "Read") {
+        entry.file = input.file_path || "";
+        entry.action = "read";
       } else if (tool === "Bash") {
         entry.command = (input.command || "").slice(0, 300);
         entry.action = "command";

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",
+        "matcher": "Edit|Write|Read|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,259 @@ 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 == "Read":
+        entry["action"] = "read"
+        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 _relative_path(filepath, project_dir):
+    try:
+        return str(Path(filepath).relative_to(project_dir))
+    except (ValueError, TypeError):
+        return Path(filepath).name if filepath else ""
+
+
+def _group_files_by_dir(filepaths, project_dir):
+    groups = {}
+    for fp in sorted(filepaths):
+        rel = _relative_path(fp, project_dir)
+        parent = str(Path(rel).parent)
+        if parent == ".":
+            parent = "(root)"
+        groups.setdefault(parent, []).append(Path(rel).name)
+    return groups
+
+
+def _classify_command(cmd):
+    if not cmd.strip():
+        return "other", ""
+    first = cmd.strip().split()[0]
+    search_cmds = {'grep', 'rg', 'ag', 'ack'}
+    explore_cmds = {'find', 'fd', 'ls', 'tree', 'du'}
+    read_cmds = {'cat', 'head', 'tail', 'less', 'more', 'wc', 'file'}
+    diff_cmds = {'diff', 'git diff', 'git log', 'git status', 'git show'}
+    test_cmds = {'pytest', 'python -m pytest', 'npm test', 'jest', 'mocha', 'cargo test', 'go test'}
+    build_cmds = {'npm run', 'npm install', 'pip install', 'make', 'cargo build', 'go build'}
+    server_cmds = {'python3 -m', 'uvicorn', 'node', 'npm start', 'flask run'}
+    git_cmds = {'git commit', 'git push', 'git add', 'git checkout', 'git branch', 'git merge', 'git stash'}
+
+    if first in search_cmds or cmd.strip().startswith('git grep'):
+        return "search", cmd
+    if first in explore_cmds:
+        return "explore", cmd
+    if first in read_cmds:
+        return "read_cmd", cmd
+    for prefix in diff_cmds:
+        if cmd.strip().startswith(prefix):
+            return "git_inspect", cmd
+    for prefix in test_cmds:
+        if cmd.strip().startswith(prefix):
+            return "test", cmd
+    for prefix in build_cmds:
+        if cmd.strip().startswith(prefix):
+            return "build", cmd
+    for prefix in git_cmds:
+        if cmd.strip().startswith(prefix):
+            return "git_write", cmd
+    for prefix in server_cmds:
+        if cmd.strip().startswith(prefix):
+            return "run", cmd
+    if first == 'curl':
+        return "api_test", cmd
+    return "other", cmd
+
+
+def _build_investigated(files_read, commands_classified, project_dir):
+    items = []
+    seen_files = set()
+
+    search_cmds = [cmd for cls, cmd in commands_classified if cls == "search"]
+    for cmd in search_cmds[:8]:
+        parts = cmd.strip().split()
+        if len(parts) >= 2:
+            pattern = None
+            for i, p in enumerate(parts):
+                if not p.startswith('-') and i > 0:
+                    pattern = p.strip("'\"")
+                    break
+            if pattern:
+                items.append(f"- Searched for `{pattern[:60]}`")
+            else:
+                items.append(f"- `{cmd[:100]}`")
+
+    read_groups = _group_files_by_dir(files_read, project_dir)
+    for dir_name, filenames in read_groups.items():
+        unique = [f for f in filenames if f not in seen_files]
+        seen_files.update(unique)
+        if not unique:
+            continue
+        if len(unique) <= 3:
+            items.append(f"- Read {', '.join(f'`{f}`' for f in unique)}")
+        else:
+            items.append(f"- Read {len(unique)} files in `{dir_name}/`")
+
+    explore_cmds = [cmd for cls, cmd in commands_classified if cls == "explore"]
+    if explore_cmds:
+        items.append(f"- Explored project structure ({len(explore_cmds)} commands)")
+
+    git_cmds = [cmd for cls, cmd in commands_classified if cls == "git_inspect"]
+    if git_cmds:
+        items.append(f"- Inspected git history/diff ({len(git_cmds)} commands)")
+
+    api_cmds = [cmd for cls, cmd in commands_classified if cls == "api_test"]
+    if api_cmds:
+        items.append(f"- Tested API endpoints ({len(api_cmds)} requests)")
+
+    return items
+
+
+def _build_learned(files_read, files_edited, files_created, commands_classified, project_dir):
+    items = []
+    read_set = {Path(f).name for f in files_read}
+    edit_set = {Path(f).name for f in files_edited}
+    create_set = {Path(f).name for f in files_created}
+
+    investigated_then_modified = read_set & edit_set
+    if investigated_then_modified:
+        names = sorted(investigated_then_modified)[:5]
+        items.append(f"- Investigated and modified: {', '.join(f'`{n}`' for n in names)}")
+
+    config_files = {f for f in (files_edited | files_created)
+                    if any(f.endswith(ext) for ext in
+                           ('.json', '.toml', '.yaml', '.yml', '.ini', '.cfg', '.env', '.conf'))}
+    if config_files:
+        items.append(f"- Configuration changes: {', '.join(f'`{Path(f).name}`' for f in sorted(config_files)[:4])}")
+
+    test_cmds = [cmd for cls, cmd in commands_classified if cls == "test"]
+    if test_cmds:
+        items.append(f"- Ran tests ({len(test_cmds)} run{'s' if len(test_cmds) != 1 else ''})")
+
+    new_only = create_set - read_set
+    if new_only:
+        items.append(f"- Created new files: {', '.join(f'`{n}`' for n in sorted(new_only)[:5])}")
+
+    return items
+
+
+def _build_completed(files_edited, files_created, commands_classified, project_dir):
+    items = []
+
+    edit_groups = _group_files_by_dir(files_edited, project_dir)
+    for dir_name, filenames in edit_groups.items():
+        if len(filenames) == 1:
+            items.append(f"- Modified `{filenames[0]}`")
+        else:
+            items.append(f"- Modified {len(filenames)} files in `{dir_name}/`: {', '.join(f'`{f}`' for f in filenames[:5])}")
+
+    create_groups = _group_files_by_dir(files_created, project_dir)
+    for dir_name, filenames in create_groups.items():
+        if len(filenames) == 1:
+            items.append(f"- Created `{filenames[0]}`")
+        else:
+            items.append(f"- Created {len(filenames)} files in `{dir_name}/`")
+
+    test_cmds = [cmd for cls, cmd in commands_classified if cls == "test"]
+    if test_cmds:
+        items.append(f"- Ran test suite")
+
+    git_writes = [cmd for cls, cmd in commands_classified if cls == "git_write"]
+    for cmd in git_writes:
+        if 'commit' in cmd:
+            items.append("- Committed changes to git")
+            break
+    for cmd in git_writes:
+        if 'push' in cmd:
+            items.append("- Pushed to remote")
+            break
+
+    build_cmds = [cmd for cls, cmd in commands_classified if cls == "build"]
+    if build_cmds:
+        items.append("- Ran build/install")
+
+    run_cmds = [cmd for cls, cmd in commands_classified if cls == "run"]
+    if run_cmds:
+        items.append("- Started/tested server")
+
+    return items
+
+
+def _build_next_steps(files_edited, files_created, commands_classified):
+    items = []
+
+    git_writes = {cmd for cls, cmd in commands_classified if cls == "git_write"}
+    has_commit = any('commit' in cmd for cmd in git_writes)
+    has_push = any('push' in cmd for cmd in git_writes)
+
+    all_changed = files_edited | files_created
+    if all_changed and not has_commit:
+        items.append("- Commit pending changes")
+    if has_commit and not has_push:
+        items.append("- Push committed changes to remote")
+
+    test_cmds = [cmd for cls, cmd in commands_classified if cls == "test"]
+    if not test_cmds and all_changed:
+        items.append("- Run tests to verify changes")
+
+    return items
+
+
 def handle_stop():
     if not CURRENT_SESSION.exists():
         return
@@ -40,9 +294,11 @@ def handle_stop():
     project_name = Path(project_dir).name
     session_id = datetime.now().strftime("%Y-%m-%d_%H%M%S")
 
+    files_read = set()
     files_edited = set()
     files_created = set()
     commands = []
+    prompts = []
     timeline = []
 
     for e in entries:
@@ -50,7 +306,14 @@ 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 == "read":
+            fp = e.get("file", "")
+            files_read.add(fp)
+            timeline.append(f"  {ts} — Read `{Path(fp).name}`")
+        elif action == "edit":
             fp = e.get("file", "")
             files_edited.add(fp)
             timeline.append(f"  {ts} — Edit `{Path(fp).name}`")
@@ -64,6 +327,8 @@ def handle_stop():
             short = cmd[:80] + "..." if len(cmd) > 80 else cmd
             timeline.append(f"  {ts} — `{short}`")
 
+    commands_classified = [_classify_command(cmd) for cmd in commands]
+
     summary_items = []
     if files_edited:
         summary_items.append(f"Modified {len(files_edited)} file{'s' if len(files_edited) != 1 else ''}")
@@ -72,12 +337,10 @@ def handle_stop():
     if commands:
         summary_items.append(f"Ran {len(commands)} command{'s' if len(commands) != 1 else ''}")
 
-    investigate_keywords = {'grep', 'find', 'cat', 'head', 'tail', 'less', 'ls', 'tree', 'rg', 'ag', 'fd', 'wc', 'diff'}
-    investigated_cmds = []
-    for cmd in commands:
-        first_word = cmd.strip().split()[0] if cmd.strip() else ''
-        if first_word in investigate_keywords:
-            investigated_cmds.append(cmd)
+    investigated = _build_investigated(files_read, commands_classified, project_dir)
+    learned = _build_learned(files_read, files_edited, files_created, commands_classified, project_dir)
+    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}`")
@@ -88,28 +351,32 @@ 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]:
-            short = cmd[:120] + "..." if len(cmd) > 120 else cmd
-            parts.append(f"- `{short}`")
+    if investigated:
+        parts.extend(investigated)
     parts.append("")
 
     parts.append("## LEARNED")
-    parts.append("")
+    if learned:
+        parts.extend(learned)
     parts.append("")
 
     parts.append("## COMPLETED")
-    if files_edited:
-        for f in sorted(files_edited):
-            parts.append(f"- Modified `{Path(f).name}`")
-    if files_created:
-        for f in sorted(files_created):
-            parts.append(f"- Created `{Path(f).name}`")
+    if completed:
+        parts.extend(completed)
     parts.append("")
 
     parts.append("## NEXT STEPS")
-    parts.append("")
+    if next_steps:
+        parts.extend(next_steps)
     parts.append("")
 
     if timeline:

package/kyp_mem/server.py

@@ -324,11 +324,20 @@ def kyp_project_context(project: str) -> str:
     """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 = []
 
+    MAX_KNOWLEDGE_CHARS = 3000
+    MAX_NOTE_PREVIEW_LINES = 6
+    MAX_SESSION_CHARS = 400
+
     knowledge_path = f"{project}/Knowledge.md"
     knowledge = vault.read(knowledge_path)
     if knowledge:
         parts.append("=== PROJECT KNOWLEDGE ===")
-        parts.append(knowledge.content)
+        content = knowledge.content
+        if len(content) > MAX_KNOWLEDGE_CHARS:
+            parts.append(content[:MAX_KNOWLEDGE_CHARS])
+            parts.append(f"\n... (truncated — use kyp_read(\"{knowledge_path}\", full=True) for complete content)")
+        else:
+            parts.append(content)
         parts.append("")
 
     project_notes = []
@@ -341,9 +350,9 @@ def kyp_project_context(project: str) -> str:
         for path, note in sorted(project_notes):
             parts.append(f"\n--- {note.title} ({path}) ---")
             preview = note.content.strip().split("\n")
-            parts.append("\n".join(preview[:10]))
-            if len(preview) > 10:
-                parts.append("...")
+            parts.append("\n".join(preview[:MAX_NOTE_PREVIEW_LINES]))
+            if len(preview) > MAX_NOTE_PREVIEW_LINES:
+                parts.append(f"... (use kyp_read(\"{path}\", full=True) for complete content)")
         parts.append("")
 
     sessions = []
@@ -360,9 +369,11 @@ def kyp_project_context(project: str) -> str:
             content = note.content
             timeline_idx = content.find("## Timeline")
             if timeline_idx > 0:
-                parts.append(content[:timeline_idx].strip())
+                content = content[:timeline_idx].strip()
+            if len(content) > MAX_SESSION_CHARS:
+                parts.append(content[:MAX_SESSION_CHARS] + "...")
             else:
-                parts.append(content[:500])
+                parts.append(content)
         parts.append("")
 
     if not parts:

package/kyp_mem/static/index.html

@@ -1573,29 +1573,52 @@ body.resizing .resize-handle { pointer-events: auto !important; }
   color: var(--text-secondary);
 }
 
-/* ============ BACKLINK CONTEXT ============ */
-.rp-item .rp-context {
-  font-size: 10px;
-  color: var(--text-muted);
-  margin-top: 2px;
-  line-height: 1.4;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.rp-item-col {
+/* ============ BACKLINK & UNLINKED ITEMS ============ */
+.rp-link-item {
   display: flex;
-  flex-direction: column;
-  padding: 5px 8px;
+  align-items: center;
+  padding: 4px 8px;
   border-radius: var(--radius-sm);
   cursor: pointer;
   margin-bottom: 1px;
   transition: background 0.1s;
+  gap: 6px;
+}
+
+.rp-link-item:hover { background: var(--bg-hover); }
+
+.rp-link-item .rp-link-icon {
+  font-size: 9px;
+  flex-shrink: 0;
+  opacity: 0.5;
+}
+
+.rp-link-item .rp-link-icon.backlink { color: var(--neon-cyan); }
+.rp-link-item .rp-link-icon.unlinked { color: var(--text-muted); }
+
+.rp-link-item .rp-link-title {
+  font-size: 12px;
+  color: var(--neon-cyan);
+  font-weight: 500;
   overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  transition: all 0.15s;
 }
 
-.rp-item-col:hover { background: var(--bg-hover); }
+.rp-link-item:hover .rp-link-title {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.rp-link-item.unlinked .rp-link-title {
+  color: var(--text-secondary);
+}
+
+.rp-link-item.unlinked:hover .rp-link-title {
+  color: var(--neon-cyan);
+  text-decoration: underline;
+}
 
 /* ============ TRANSITIONS ============ */
 .fade-in { animation: fadeIn 0.15s ease; }
@@ -2188,10 +2211,8 @@ function renderRightPanel(note) {
     document.getElementById('bl-count').textContent = backlinks.length;
     backlinks.forEach(bl => {
       const item = document.createElement('div');
-      item.className = 'rp-item-col';
-      let html = `<span class="rp-title rp-backlink-title" style="font-size:11px">${bl.title || bl.path || bl}</span>`;
-      if (bl.context) html += `<span class="rp-context">${bl.context}</span>`;
-      item.innerHTML = html;
+      item.className = 'rp-link-item';
+      item.innerHTML = `<span class="rp-link-icon backlink">&#8592;</span><span class="rp-link-title">${bl.title || bl.path || bl}</span>`;
       item.addEventListener('click', () => loadNote(bl.path || bl));
       blList.appendChild(item);
     });
@@ -2244,10 +2265,8 @@ function renderRightPanel(note) {
     document.getElementById('unlinked-count').textContent = unlinked.length;
     unlinked.forEach(u => {
       const item = document.createElement('div');
-      item.className = 'rp-item-col';
-      let html = `<span class="rp-title" style="font-size:11px;color:var(--text-secondary)">${u.title}</span>`;
-      if (u.context) html += `<span class="rp-context">${u.context}</span>`;
-      item.innerHTML = html;
+      item.className = 'rp-link-item unlinked';
+      item.innerHTML = `<span class="rp-link-icon unlinked">&#8776;</span><span class="rp-link-title">${u.title}</span>`;
       item.addEventListener('click', () => loadNote(u.path));
       ulList.appendChild(item);
     });
@@ -2905,6 +2924,23 @@ async function init() {
   `;
 }
 
+// --- Auto-refresh: poll for vault changes ---
+let lastKnownStats = null;
+
+async function pollForChanges() {
+  try {
+    const stats = await fetchJSON('/api/stats');
+    const key = `${stats.notes}:${stats.links}:${stats.tags}`;
+    if (lastKnownStats && lastKnownStats !== key) {
+      await refreshTree();
+      if (currentPath) loadNote(currentPath);
+    }
+    lastKnownStats = key;
+  } catch {}
+}
+
+setInterval(pollForChanges, 3000);
+
 initResize();
 initGraphResize();
 init();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kyp-mem",
-  "version": "0.4.1",
-  "description": "Know Your Project — Persistent knowledge base for AI agents. MCP-powered with wikilinks, backlinks, auto-learning, and neon web UI.",
+  "version": "0.4.3",
+  "description": "Know Your Project — Persistent & Session level 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"}