kyp-mem 0.4.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/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"