kyp-mem 0.3.0 → 0.4.1

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.1"

package/kyp_mem/hooks.py

@@ -64,29 +64,53 @@ def handle_stop():
             short = cmd[:80] + "..." if len(cmd) > 80 else cmd
             timeline.append(f"  {ts} — `{short}`")
 
+    summary_items = []
+    if files_edited:
+        summary_items.append(f"Modified {len(files_edited)} file{'s' if len(files_edited) != 1 else ''}")
+    if files_created:
+        summary_items.append(f"Created {len(files_created)} file{'s' if len(files_created) != 1 else ''}")
+    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)
+
     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("")
+
+    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}`")
+    parts.append("")
+
+    parts.append("## LEARNED")
+    parts.append("")
+    parts.append("")
+
+    parts.append("## COMPLETED")
     if files_edited:
-        parts.append("## Files Modified")
         for f in sorted(files_edited):
-            parts.append(f"- `{f}`")
-        parts.append("")
-
+            parts.append(f"- Modified `{Path(f).name}`")
     if files_created:
-        parts.append("## Files Created")
         for f in sorted(files_created):
-            parts.append(f"- `{f}`")
-        parts.append("")
+            parts.append(f"- Created `{Path(f).name}`")
+    parts.append("")
 
-    if commands:
-        parts.append("## Commands Run")
-        for cmd in commands[:25]:
-            short = cmd[:120] + "..." if len(cmd) > 120 else cmd
-            parts.append(f"- `{short}`")
-        parts.append("")
+    parts.append("## NEXT STEPS")
+    parts.append("")
+    parts.append("")
 
     if timeline:
         parts.append("## Timeline")
@@ -102,7 +126,7 @@ def handle_stop():
     from .vault import Vault
 
     vault = Vault(get_vault_path())
-    vault.write_note(f"Sessions/{session_id}.md", content, tags, {})
+    vault.write_note(f"{project_name}/Sessions/{session_id}.md", content, tags, {})
 
     CURRENT_SESSION.unlink(missing_ok=True)
 

package/kyp_mem/server.py

@@ -1,6 +1,7 @@
 """KYP-MEM MCP server — headless knowledge base for AI agents."""
 
 import json
+from datetime import datetime
 from mcp.server.fastmcp import FastMCP
 from .config import get_vault_path
 from .vault import Vault
@@ -10,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."""
@@ -95,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"
 
@@ -191,3 +247,125 @@ def kyp_stats() -> str:
         f"  Links: {s['links']}\n"
         f"  Backlinks: {s['backlinks']}"
     )
+
+
+@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."""
+    session_id = datetime.now().strftime("%Y-%m-%d_%H%M%S")
+    parts = [f"# Session {session_id}", ""]
+    parts.append(f"**Project:** {project}")
+    parts.append("")
+    parts.append("## Summary")
+    parts.append(summary or "")
+    parts.append("")
+    parts.append("## INVESTIGATED")
+    parts.append(investigated or "")
+    parts.append("")
+    parts.append("## LEARNED")
+    parts.append(learned or "")
+    parts.append("")
+    parts.append("## COMPLETED")
+    parts.append(completed or "")
+    parts.append("")
+    parts.append("## NEXT STEPS")
+    parts.append(next_steps or "")
+
+    content = "\n".join(parts)
+    tags = ["session", "manual", project.lower().replace(" ", "-")]
+    path = f"{project}/Sessions/{session_id}.md"
+    vault.write_note(path, content, tags, {})
+    return f"Created session: {path}"
+
+
+@mcp.tool()
+def kyp_sessions(project: str = "", limit: int = 10) -> str:
+    """List sessions, optionally filtered by project. Shows most recent first."""
+    sessions = []
+    for path, note in vault.index.notes.items():
+        if "/Sessions/" not in path and not path.startswith("Sessions/"):
+            continue
+        if project and not path.lower().startswith(project.lower() + "/"):
+            continue
+        sessions.append((path, note))
+    sessions.sort(key=lambda s: s[0], reverse=True)
+    sessions = sessions[:limit]
+    if not sessions:
+        return "No sessions found." + (f" (project filter: {project})" if project else "")
+    lines = ["Sessions:", ""]
+    for path, note in sessions:
+        tags = f" [{', '.join(note.tags)}]" if note.tags else ""
+        date = note.created or note.updated or ""
+        lines.append(f"  {date} — {note.title} ({path}){tags}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+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 = []
+
+    knowledge_path = f"{project}/Knowledge.md"
+    knowledge = vault.read(knowledge_path)
+    if knowledge:
+        parts.append("=== PROJECT KNOWLEDGE ===")
+        parts.append(knowledge.content)
+        parts.append("")
+
+    project_notes = []
+    for path, note in vault.index.notes.items():
+        if path.startswith(f"{project}/") and "/Sessions/" not in path and path != knowledge_path:
+            project_notes.append((path, note))
+
+    if project_notes:
+        parts.append("=== PROJECT NOTES ===")
+        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("")
+
+    sessions = []
+    for path, note in vault.index.notes.items():
+        if path.startswith(f"{project}/Sessions/"):
+            sessions.append((path, note))
+    sessions.sort(key=lambda s: s[0], reverse=True)
+    recent = sessions[:5]
+
+    if recent:
+        parts.append(f"=== RECENT SESSIONS ({len(recent)} of {len(sessions)}) ===")
+        for path, note in recent:
+            parts.append(f"\n--- {note.title} ---")
+            content = note.content
+            timeline_idx = content.find("## Timeline")
+            if timeline_idx > 0:
+                parts.append(content[:timeline_idx].strip())
+            else:
+                parts.append(content[:500])
+        parts.append("")
+
+    if not parts:
+        return f"No context found for project '{project}'. Create a Knowledge.md to get started."
+
+    return "\n".join(parts)