docdex 0.2.16 → 0.2.18

package/assets/agents.md

@@ -0,0 +1,117 @@
+# Docdex Agent Usage Instructions
+
+> Context for AI Agents: Docdex is your local-first Dual-Lobe Memory and Code Intelligence daemon. Unlike simple vector stores, it provides structural understanding of code (AST/Graph), persistent behavioral profiles (Agent Memory), and gated web enrichment, all strictly scoped to the local machine.
+
+## Identity & Architecture
+
+Docdex (Documentation Indexer) serves as your persistent "brain" on the user's machine. It operates on a Waterfall Retrieval model:
+
+1. Local First (Tier 1): Instant search of repo code, symbols, and ingested library documentation.
+2. Web Enrichment (Tier 2): Gated fallback to DuckDuckGo/Headless Chrome only when local confidence is low or explicitly requested.
+3. Cognition (Tier 3): Local LLM inference (Ollama) with context assembly.
+
+Key Constraints:
+
+- Repo Isolation: Data never bleeds between repositories. You must identify the active repo for every operation.
+- Hierarchy of Truth: Technical Truth (Code/Repo Memory) > Behavioral Truth (Profile Memory).
+- Privacy: Code is never uploaded to a cloud vector store.
+
+## The Dual-Lobe Memory System
+
+Docdex v2.1 introduces a strict separation between "facts" and "preferences." Use the correct lobe for the task.
+
+### 1. Repo Memory (The Hippocampus)
+
+- Scope: Project-bound. Specific to the current repository.
+- Content: Technical facts, architectural decisions, logic locations.
+- Example: "The calculateTax function is located in utils/money.ts."
+- Tools: docdex_memory_save, docdex_memory_recall
+
+### 2. Profile Memory (The Neocortex)
+
+- Scope: Global / agent-bound. Persists across all projects.
+- Content: Your persona, user preferences, coding style, tooling constraints.
+- Example: "Always use Zod for validation," or "User prefers strict TypeScript types."
+- Tools: docdex_save_preference, docdex_get_profile
+- Usage: Use this to "learn" from corrections. If a user corrects your style, save it here so you do not repeat the mistake in a different repo.
+
+## Tool Capabilities (MCP & HTTP)
+
+### A. Semantic Search & Web (Waterfall)
+
+Standard retrieval. The daemon automatically handles the waterfall (Local -> Web).
+
+| MCP Tool | Purpose |
+| --- | --- |
+| docdex_search | Search code, docs, and ingested libraries. Returns ranked snippets. |
+| docdex_web_research | Explicitly trigger Tier 2 web discovery (DDG + Headless Chrome). Use when you need external docs not present locally. |
+
+### B. Code Intelligence (AST & Graph)
+
+Precision tools for structural analysis. Do not rely on text search for definitions or dependencies.
+
+| MCP Tool | Purpose |
+| --- | --- |
+| docdex_symbols | Get exact definitions/signatures for a file. |
+| docdex_ast | Specific AST nodes (e.g., "Find all class definitions"). |
+| docdex_impact_diagnostics | Check for broken/dynamic imports. |
+| HTTP /v1/graph/impact | Impact Analysis: "What breaks if I change this?" Returns inbound/outbound dependencies. |
+
+### C. Memory Operations
+
+| MCP Tool | Purpose |
+| --- | --- |
+| docdex_memory_save | Store a technical fact about the current repo. |
+| docdex_memory_recall | Retrieve technical facts about the current repo. |
+| docdex_save_preference | Store a global user preference (Style, Tooling, Constraint). |
+| docdex_get_profile | Retrieve global preferences. |
+
+## Interaction Patterns
+
+### 1. Reasoning Workflow
+
+When answering a complex coding query, follow this "Reasoning Trace":
+
+1. Retrieve Profile: Call docdex_get_profile to load user style/constraints (e.g., "Use functional components").
+2. Search Code: Call docdex_search or docdex_symbols to find the relevant code.
+3. Check Memory: Call docdex_memory_recall for project-specific caveats (e.g., "Auth logic was refactored last week").
+4. Synthesize: Generate code that matches the Repo Truth while adhering to the Profile Style.
+
+### 2. Handling Corrections (Learning)
+
+If the user says: "I told you, we do not use Moment.js here, use date-fns!"
+
+- Action: Call docdex_save_preference
+- category: "constraint"
+- content: "Do not use Moment.js; prefer date-fns."
+- agent_id: "default" (or active agent ID)
+
+### 3. Impact Analysis
+
+If the user asks: "Safe to delete getUser?"
+
+- Action: Call GET /v1/graph/impact?file=src/user.ts
+- Output: Analyze the inbound edges. If the list is not empty, it is unsafe.
+
+## Operational Context
+
+### Repository Identification
+
+Docdex is multi-tenant via isolation.
+
+- HTTP: Send x-docdex-repo-id header or repo_id query param if communicating with the singleton daemon.
+- MCP: Ensure project_root or repo_path is passed in tool arguments if the session is not pinned.
+
+### Error Codes
+
+- missing_repo: You failed to specify which repo to query.
+- rate_limited: Back off. The system protects the web scraper and LLM.
+- stale_index: The AST parser drifted. Suggest running docdexd index.
+- memory_disabled: The user has explicitly disabled memory features.
+
+### Hardware Awareness
+
+Docdex adapts to the host.
+
+- Project Mapping: On constrained hardware, docdex uses a "Spotlight Heuristic" to show you only a skeletal file tree based on your role keywords, rather than the full file system.
+- LLM: It may be running a quantized model (e.g., phi3.5) or a heavy model (llama3.1:70b) depending on VRAM. Trust the daemon's token limits; it handles truncation.

package/bin/docdex-mcp-server.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const {
+  detectPlatformKey,
+  targetTripleForPlatformKey,
+  assetPatternForPlatformKey,
+  UnsupportedPlatformError
+} = require("../lib/platform");
+
+function run() {
+  let platformKey;
+  try {
+    platformKey = detectPlatformKey();
+  } catch (err) {
+    if (err instanceof UnsupportedPlatformError) {
+      const detected = `${err.details?.platform ?? process.platform}/${err.details?.arch ?? process.arch}`;
+      const libc = err.details?.libc ? `/${err.details.libc}` : "";
+      console.error(`[docdex] unsupported platform (${detected}${libc})`);
+      console.error(`[docdex] error code: ${err.code}`);
+      console.error("[docdex] No download/run was attempted for this platform.");
+      if (Array.isArray(err.details?.supportedPlatformKeys) && err.details.supportedPlatformKeys.length) {
+        console.error(`[docdex] Supported platforms: ${err.details.supportedPlatformKeys.join(", ")}`);
+      }
+      if (typeof err.details?.candidatePlatformKey === "string") {
+        console.error(`[docdex] Asset naming pattern: ${assetPatternForPlatformKey(err.details.candidatePlatformKey)}`);
+      }
+      console.error("[docdex] Next steps: use a supported platform or build from source (Rust).");
+      process.exit(err.exitCode || 3);
+      return;
+    }
+    console.error(`[docdex] failed to detect platform: ${err?.message || String(err)}`);
+    process.exit(1);
+    return;
+  }
+
+  const basePath = path.join(__dirname, "..", "dist", platformKey);
+  const binaryPath = path.join(
+    basePath,
+    process.platform === "win32" ? "docdex-mcp-server.exe" : "docdex-mcp-server"
+  );
+
+  if (!fs.existsSync(binaryPath)) {
+    console.error(
+      `[docdex] Missing MCP server binary for ${platformKey}. Try reinstalling or set DOCDEX_MCP_SERVER_BIN.`
+    );
+    try {
+      console.error(`[docdex] Expected target triple: ${targetTripleForPlatformKey(platformKey)}`);
+      console.error(`[docdex] Asset naming pattern: ${assetPatternForPlatformKey(platformKey)}`);
+    } catch {}
+    process.exit(1);
+  }
+
+  const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code ?? 1));
+  child.on("error", (err) => {
+    console.error(`[docdex] failed to launch MCP server: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+run();

package/bin/docdex.js

@@ -27,6 +27,24 @@ function printLines(lines, { stderr } = {}) {
   }
 }
 
+function readInstallMetadata({ fsModule, pathModule, basePath }) {
+  if (!fsModule || typeof fsModule.readFileSync !== "function") return null;
+  const metadataPath = pathModule.join(basePath, "docdexd-install.json");
+  try {
+    const raw = fsModule.readFileSync(metadataPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function formatInstallSource(meta) {
+  const source = meta?.archive?.source;
+  if (!source || typeof source !== "string") return "unknown";
+  if (source === "local") return "local binary";
+  return `release (${source})`;
+}
+
 function runDoctor() {
   const platform = process.platform;
   const arch = process.arch;
@@ -55,6 +73,9 @@ function runDoctor() {
     const targetTriple = targetTripleForPlatformKey(platformKey);
     const expectedAssetName = artifactName(platformKey);
     const expectedAssetPattern = assetPatternForPlatformKey(platformKey, { exampleAssetName: expectedAssetName });
+    const basePath = path.join(__dirname, "..", "dist", platformKey);
+    const installMeta = readInstallMetadata({ fsModule: fs, pathModule: path, basePath });
+    const installSource = formatInstallSource(installMeta);
 
     report = {
       exitCode: 0,
@@ -66,7 +87,8 @@ function runDoctor() {
         `[docdex] Platform key: ${platformKey}`,
         `[docdex] Expected target triple: ${targetTriple}`,
         `[docdex] Expected release asset: ${expectedAssetName}`,
-        `[docdex] Asset naming pattern: ${expectedAssetPattern}`
+        `[docdex] Asset naming pattern: ${expectedAssetPattern}`,
+        `[docdex] Install source: ${installSource}`
       ]
     };
   } catch (err) {
@@ -152,6 +174,10 @@ function run() {
     basePath,
     process.platform === "win32" ? "docdexd.exe" : "docdexd"
   );
+  const mcpBinaryPath = path.join(
+    basePath,
+    process.platform === "win32" ? "docdex-mcp-server.exe" : "docdex-mcp-server"
+  );
 
   if (!fs.existsSync(binaryPath)) {
     console.error(`[docdex] Missing binary for ${platformKey}. Try reinstalling or set DOCDEX_DOWNLOAD_REPO to a repo with release assets.`);
@@ -162,7 +188,11 @@ function run() {
     process.exit(1);
   }
 
-  const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+  const env = { ...process.env };
+  if (!env.DOCDEX_MCP_SERVER_BIN && fs.existsSync(mcpBinaryPath)) {
+    env.DOCDEX_MCP_SERVER_BIN = mcpBinaryPath;
+  }
+  const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit", env });
   child.on("exit", (code) => process.exit(code ?? 1));
   child.on("error", (err) => {
     console.error(`[docdex] failed to launch binary: ${err.message}`);