feat(claude-code): add knowledge tools via Python MCP server + claude/claude-code harnesses (#1428)

Plugin changes (hindsight-integrations/claude-code/):
- Add scripts/mcp_server.py — Python FastMCP stdio server exposing 7
  agent_knowledge_* tools (list/get/create/update/delete pages, recall,
  ingest). Each tool accepts optional bank_id parameter.
- Add scripts/inject_bank_id.py — PreToolUse hook that intercepts
  mcp__hindsight__agent_knowledge_* calls and injects bank_id from
  session context (cwd, agentName) via updatedInput.
- Add .mcp.json — plugin MCP server config (stdio transport)
- Add skills/agent-knowledge/SKILL.md
- Add enableKnowledgeTools config flag (MCP server exits if disabled)
- Make client.request() public (was _request)
- Bump plugin to v0.5.0

CLI changes (hindsight-tools/self-driving-agents/):
- Re-add --harness claude (Chat/Cowork skill zip generation, lost in
  hermes PR merge)
- Add --harness claude-code (marketplace install, config, knowledge tools)
- Add tests for both harnesses

Author: nicoloboschi

hindsight-integrations/claude-code/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hindsight-memory",
-  "description": "Automatic long-term memory for Claude Code via Hindsight. Recalls relevant memories before each prompt and retains conversation transcripts after each response.",
-  "version": "0.4.0",
+  "description": "Automatic long-term memory for Claude Code via Hindsight. Recalls relevant memories before each prompt, retains conversation transcripts, and provides knowledge page tools.",
+  "version": "0.5.0",
   "author": {"name": "Hindsight Team", "url": "https://vectorize.io/hindsight"},
   "license": "MIT",
   "keywords": ["memory", "hindsight", "recall", "retain"]

hindsight-integrations/claude-code/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hindsight": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp_server.py"]
+    }
+  }
+}

hindsight-integrations/claude-code/hooks/hooks.json

@@ -22,6 +22,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "mcp__hindsight__agent_knowledge_.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/inject_bank_id.py\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

hindsight-integrations/claude-code/scripts/inject_bank_id.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: inject bank_id into agent_knowledge_* MCP tool calls.
+
+Intercepts mcp__hindsight__agent_knowledge_* tool calls and injects
+the resolved bank_id into tool_input, using the same derivation logic
+as the recall/retain hooks (config chain + cwd context).
+
+Exit codes:
+  0 — always (allow the tool call to proceed)
+"""
+
+import json
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from lib.bank import derive_bank_id
+from lib.config import debug_log, load_config
+
+
+def main():
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        return
+
+    tool_input = hook_input.get("tool_input", {})
+
+    # Skip if bank_id already provided (explicit override)
+    if tool_input.get("bank_id"):
+        return
+
+    config = load_config()
+
+    if not config.get("enableKnowledgeTools"):
+        return
+
+    bank_id = derive_bank_id(hook_input, config)
+    debug_log(config, f"Injecting bank_id={bank_id} into {hook_input.get('tool_name')}")
+
+    # Return updatedInput with bank_id injected
+    updated = dict(tool_input)
+    updated["bank_id"] = bank_id
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "updatedInput": updated,
+        }
+    }
+    json.dump(output, sys.stdout)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        print(f"[Hindsight] inject_bank_id error: {e}", file=sys.stderr)
+        sys.exit(0)

hindsight-integrations/claude-code/scripts/lib/client.py

@@ -57,7 +57,7 @@ def _headers(self) -> dict:
             headers["Authorization"] = f"Bearer {self.api_token}"
         return headers
 
-    def _request(self, method: str, path: str, body: Optional[dict] = None, timeout: int = DEFAULT_TIMEOUT) -> dict:
+    def request(self, method: str, path: str, body: Optional[dict] = None, timeout: int = DEFAULT_TIMEOUT) -> dict:
         url = f"{self.api_url}{path}"
         data = json.dumps(body).encode() if body else None
         req = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
@@ -115,7 +115,7 @@ def recall(
             body["budget"] = budget
         if types:
             body["types"] = types
-        return self._request("POST", path, body, timeout=timeout)
+        return self.request("POST", path, body, timeout=timeout)
 
     def retain(
         self,
@@ -147,7 +147,7 @@ def retain(
             "items": [item],
             "async": True,
         }
-        return self._request("POST", path, body, timeout=timeout)
+        return self.request("POST", path, body, timeout=timeout)
 
     def set_bank_mission(
         self, bank_id: str, mission: str, retain_mission: Optional[str] = None, timeout: int = 15
@@ -161,4 +161,4 @@ def set_bank_mission(
         updates = {"reflect_mission": mission}
         if retain_mission:
             updates["retain_mission"] = retain_mission
-        return self._request("PATCH", path, {"updates": updates}, timeout=timeout)
+        return self.request("PATCH", path, {"updates": updates}, timeout=timeout)

hindsight-integrations/claude-code/scripts/mcp_server.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Hindsight MCP server for Claude Code plugin.
+
+Runs as a stdio subprocess managed by the plugin system.
+Exposes knowledge tools (list/get/create/update/delete pages, recall, ingest).
+Reuses the existing plugin config chain and client.
+
+Each tool accepts an optional bank_id parameter. When omitted, falls back to the
+default bank derived from config at startup. The PreToolUse hook (inject_bank_id.py)
+injects bank_id from session context (cwd, agentName) before calls reach here.
+"""
+
+import json
+import os
+import sys
+import urllib.parse
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from mcp.server.fastmcp import FastMCP
+
+from lib.client import HindsightClient
+from lib.config import debug_log, load_config
+from lib.daemon import get_api_url
+from lib.bank import derive_bank_id
+
+# ── Server setup ────────────────────────────────────────
+
+mcp = FastMCP("hindsight")
+
+# Resolve config at startup
+_config = load_config()
+_dbg = lambda *a: debug_log(_config, *a)
+
+if not _config.get("enableKnowledgeTools"):
+    _dbg("Knowledge tools disabled (enableKnowledgeTools=false), MCP server exiting")
+    sys.exit(0)
+
+try:
+    _api_url = get_api_url(_config, debug_fn=_dbg, allow_daemon_start=True)
+except Exception as e:
+    print(f"[Hindsight MCP] Failed to resolve API URL: {e}", file=sys.stderr)
+    sys.exit(1)
+
+_hook_input = {"cwd": os.getcwd(), "session_id": ""}
+_default_bank_id = derive_bank_id(_hook_input, _config)
+_client = HindsightClient(_api_url, _config.get("hindsightApiToken"))
+
+_dbg(f"MCP server starting — API: {_api_url}, default bank: {_default_bank_id}")
+
+
+def _bank(bank_id: str = "") -> str:
+    """Resolve bank ID: use explicit value if provided, else fall back to default."""
+    return bank_id if bank_id else _default_bank_id
+
+
+def _encode_bank(bank_id: str) -> str:
+    return urllib.parse.quote(bank_id, safe="")
+
+
+# ── Mental model defaults ───────────────────────────────
+
+PAGE_DEFAULTS = {
+    "mode": "delta",
+    "refresh_after_consolidation": True,
+    "fact_types": ["observation"],
+    "exclude_mental_models": True,
+}
+
+# ── Tools ───────────────────────────────────────────────
+
+
+@mcp.tool()
+def agent_knowledge_list_pages(bank_id: str = "") -> str:
+    """List all your knowledge pages (IDs and names only). Use agent_knowledge_get_page to read the full content of a specific page."""
+    bid = _bank(bank_id)
+    resp = _client.request("GET", f"/v1/default/banks/{_encode_bank(bid)}/mental-models", timeout=10)
+    return json.dumps(resp, indent=2)
+
+
+@mcp.tool()
+def agent_knowledge_get_page(page_id: str, bank_id: str = "") -> str:
+    """Read a specific knowledge page by its ID. Returns the full synthesized content."""
+    bid = _bank(bank_id)
+    resp = _client.request(
+        "GET", f"/v1/default/banks/{_encode_bank(bid)}/mental-models/{page_id}?detail=full", timeout=10
+    )
+    return json.dumps(resp, indent=2)
+
+
+@mcp.tool()
+def agent_knowledge_create_page(page_id: str, name: str, source_query: str, bank_id: str = "") -> str:
+    """Create a new knowledge page. The source_query is a question the system re-asks after each consolidation to rebuild the page from conversation observations. Pages auto-update as you have more conversations."""
+    bid = _bank(bank_id)
+    resp = _client.request(
+        "POST",
+        f"/v1/default/banks/{_encode_bank(bid)}/mental-models",
+        body={
+            "id": page_id,
+            "name": name,
+            "source_query": source_query,
+            "max_tokens": 4096,
+            "trigger": PAGE_DEFAULTS,
+        },
+        timeout=15,
+    )
+    return json.dumps(resp, indent=2)
+
+
+@mcp.tool()
+def agent_knowledge_update_page(page_id: str, name: str = "", source_query: str = "", bank_id: str = "") -> str:
+    """Update a page's name or source query. The content will re-synthesize on next consolidation."""
+    body = {}
+    if name:
+        body["name"] = name
+    if source_query:
+        body["source_query"] = source_query
+    if not body:
+        return json.dumps({"error": "Provide name or source_query to update"})
+    bid = _bank(bank_id)
+    resp = _client.request(
+        "PATCH", f"/v1/default/banks/{_encode_bank(bid)}/mental-models/{page_id}", body=body, timeout=10
+    )
+    return json.dumps(resp, indent=2)
+
+
+@mcp.tool()
+def agent_knowledge_delete_page(page_id: str, bank_id: str = "") -> str:
+    """Permanently delete a knowledge page."""
+    bid = _bank(bank_id)
+    resp = _client.request("DELETE", f"/v1/default/banks/{_encode_bank(bid)}/mental-models/{page_id}", timeout=10)
+    return json.dumps(resp, indent=2)
+
+
+@mcp.tool()
+def agent_knowledge_recall(query: str, max_results: int = 10, bank_id: str = "") -> str:
+    """Search across all retained conversations and documents for specific facts, numbers, or details not covered by your knowledge pages."""
+    bid = _bank(bank_id)
+    resp = _client.recall(bank_id=bid, query=query, max_tokens=max_results, budget="mid", timeout=10)
+    return json.dumps(resp, indent=2)
+
+
+@mcp.tool()
+def agent_knowledge_ingest(title: str, content: str, bank_id: str = "") -> str:
+    """Upload a document into your memory bank. Pass the full raw content — never summarize before ingesting. The title becomes the document ID (re-ingesting replaces it)."""
+    bid = _bank(bank_id)
+    doc_id = title.lower().replace(" ", "-")
+    resp = _client.retain(bank_id=bid, content=content, document_id=doc_id, timeout=15)
+    return json.dumps(resp, indent=2)
+
+
+# ── Entry point ─────────────────────────────────────────
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")