full Claude Code Recipe

Author: jose-compu

.claude/mcp.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "logosdb": {
-      "command": "npx",
-      "args": ["-y", "logosdb-mcp-server"],
+      "command": "node",
+      "args": ["./mcp/dist/index.js"],
       "env": {
         "LOGOSDB_PATH": "./.logosdb"
       }

CHANGELOG

@@ -10,6 +10,8 @@ logosdb change log
     `search_top_k` and `match_rank` (closes #96).
   * README: Claude Code slash-commands table and `.claude/commands/` in repository contents (closes #95).
   * `.claude/commands/search.md` and `forget.md` updated for the new tool parameters.
+  * Root npm workspace (`package.json` / `package-lock.json`): `npm install` at repo root builds MCP;
+    `.claude/mcp.json` runs **`node ./mcp/dist/index.js`** for Claude Code in this clone.
 
 0.7.7  (2026-05-11)
 -------------------

CONTRIBUTING.md

@@ -10,6 +10,7 @@ Thank you for your interest in contributing to LogosDB. This document outlines t
 - C++17-capable compiler (GCC 9+, Clang 12+, Apple Clang 13+, MSVC 2019+)
 - Python 3.9+ (for Python bindings and tests)
 - Git with submodule support
+- Node.js 18+ (optional — only for building **logosdb-mcp-server** / Claude Code `.claude/mcp.json` in this repo)
 
 ### Building
 
@@ -28,6 +29,16 @@ cmake -DCMAKE_BUILD_TYPE=Release -G Ninja ..
 ninja
 ```
 
+### Claude Code (optional)
+
+This repo’s [`.claude/mcp.json`](.claude/mcp.json) points at **`./mcp/dist/index.js`**. From the repo root:
+
+```bash
+npm install
+```
+
+That builds the MCP server (`mcp` workspace `prepare` → `tsc`). Use `npm run mcp:build` after MCP TypeScript changes.
+
 Build targets:
 - `logosdb` — static library (`liblogosdb.a`)
 - `logosdb-cli` — command-line tool

README.md

@@ -66,7 +66,7 @@ Target versions and issue assignment match **[GitHub milestones](https://github.
 ### [0.7.7](https://github.com/jose-compu/logosdb/milestone/7) — patch (`0.x.Z`)
 
   * [#74](https://github.com/jose-compu/logosdb/issues/74) — security: harden encoding and injection surfaces across MCP, CLI, and integrations
-  * [#9](https://github.com/jose-compu/logosdb/issues/9) — Sanitizer builds (ASan/UBSan/TSan) and a libFuzzer target
+  * [#9](https://github.com/jose-compu/logosdb/issues/9) — libFuzzer JSON harness in CI; local ASan/UBSan builds possible; full-tree sanitizer CI not enabled (vendored hnswlib noise)
 
 ### [0.7.8](https://github.com/jose-compu/logosdb/milestone/14) — patch (`0.x.Z`)
 
@@ -489,9 +489,57 @@ logosdb-cli search /tmp/mydb --query-file q.bin --top-k 5
 exposes LogosDB to **Claude Code** (and any other MCP client) over stdio.  It lets Claude index
 files, persist knowledge across sessions, and do semantic search without leaving the conversation.
 
-### Quick start
+### Claude Code: complete recipe
 
-**1. Add to `.claude/mcp.json`** in your project (or to `~/.claude.json` for global use):
+Follow these steps in order. Claude Code spawns the MCP server with **working directory = your project root** (the folder you opened); paths in `mcp.json` and `LOGOSDB_PATH` are resolved relative to that cwd unless you use absolute paths.
+
+#### 1. Prerequisites
+
+- **Node.js** 18 or newer on your `PATH` (`node -v`, `npm -v`). For the published package you also need **`npx`**.
+- **Claude Code** installed and signed in ([overview](https://docs.anthropic.com/en/docs/claude-code/overview)).
+- Decide **where the DB lives**: `LOGOSDB_PATH` (default `./.logosdb`) is created under the project root; add the directory to `.gitignore` if you do not want it committed.
+
+#### 2. Install the server (pick one)
+
+**Option A — This repository (local `node`, no `npx`).** From the **repository root**:
+
+```bash
+npm install
+```
+
+That installs the `mcp` workspace and runs **`prepare`**, which compiles TypeScript to [`mcp/dist/index.js`](mcp/dist/index.js). After you change MCP sources, run `npm run mcp:build` at the root or `npm run build` inside `mcp/`.
+
+**Option B — Any other project (published [`logosdb-mcp-server`](https://www.npmjs.com/package/logosdb-mcp-server)).** In your app’s root:
+
+```bash
+npm install logosdb-mcp-server
+```
+
+You can still invoke it without a project dependency via `npx -y logosdb-mcp-server` (see Option C).
+
+#### 3. Register the MCP server in Claude Code
+
+Project-local config lives in **`.claude/mcp.json`** at the repository root. User-wide config is **`~/.claude.json`** (same `mcpServers` shape). Only one definition named `logosdb` is needed.
+
+**If you use Option A (this clone):** the repo already contains [`.claude/mcp.json`](.claude/mcp.json):
+
+```json
+{
+  "mcpServers": {
+    "logosdb": {
+      "command": "node",
+      "args": ["./mcp/dist/index.js"],
+      "env": {
+        "LOGOSDB_PATH": "./.logosdb"
+      }
+    }
+  }
+}
+```
+
+Open **this folder** as the Claude Code project so `./mcp/dist/index.js` resolves. If the client’s cwd is **not** the repo root, set `"args"` to an **absolute** path to `mcp/dist/index.js` (see [Installing locally — Option C](#installing-locally-without-npx)).
+
+**If you use Option B or prefer always-latest from npm (Option C):** create or merge `.claude/mcp.json`:
 
 ```json
 {
@@ -507,30 +555,73 @@ files, persist knowledge across sessions, and do semantic search without leaving
 }
 ```
 
-By default the MCP server uses **local Transformers.js** embeddings (no API keys). Add `EMBEDDING_PROVIDER` / keys only if you want cloud or [Ollama](https://ollama.com) — see `mcp/README.md`.
+Default embeddings are **local Transformers.js** (no API keys); first run may download model weights. Optional **Ollama / OpenAI / Voyage** env vars are documented in [`mcp/README.md`](mcp/README.md#configure).
 
-**Google Antigravity:** same stdio + `npx` setup; step-by-step is in [`mcp/README.md` — Google Antigravity](mcp/README.md#google-antigravity).
+#### 4. Path rules for `logosdb_index_file`
 
-**2. Start Claude Code** — the server is launched automatically on first tool call.
+The server only indexes files that resolve under **`process.cwd()`** or **`LOGOSDB_INDEX_ROOT`** (if set). Symlinks that escape those roots are rejected. Keep indexing paths inside the project you opened, or set `LOGOSDB_INDEX_ROOT` to an absolute allowed root (details in [`mcp/README.md` — Path confinement](mcp/README.md#path-confinement-logosdb_index_file)).
 
-**3. Use it in conversation:**
+#### 5. Reload Claude Code and verify
 
-```
-> Index the src/ directory into a "code" namespace
-> Find where JWT tokens are validated
-> Remember that we decided to use UUIDs for all primary keys
-```
+- **Restart** Claude Code or reload MCP configuration after editing `mcp.json`.
+- The **logosdb** server starts on **first tool use** (stdio).
+- Ask the agent to run **`logosdb_list`** (or check the MCP tools panel). You should see namespaces (possibly empty) rather than a spawn error.
+
+#### 6. Index, search, delete
+
+- **Natural language:** e.g. “Index `src/` into the `code` namespace”, “Search the codebase for JWT validation”.
+- **Slash commands (optional):** if `.claude/commands/` is present in the project (this repo ships them), use `/index`, `/search`, `/forget` — see the table below.
+- **Snippet memory:** the agent can call **`logosdb_index`** for short text; **`logosdb_index_file`** chunks files and directories.
+
+Use **one embedding backend consistently** per namespace on disk (do not change model dimension on existing data). See [Environment variables](#environment-variables) and [`mcp/README.md`](mcp/README.md).
+
+#### 7. Optional: agent instructions
+
+Copy the **`CLAUDE.md`** template block from [Agent instructions (`CLAUDE.md` and similar)](#agent-instructions-claudemd-and-similar) into your project so the agent indexes and searches without being reminded every session.
+
+#### 8. Troubleshooting
+
+| Symptom | What to try |
+|--------|----------------|
+| MCP fails to start / “Cannot find module” | From the same cwd Claude uses, run `node ./mcp/dist/index.js` (Option A) or `npx -y logosdb-mcp-server` (Option C) in a terminal; fix missing `npm install` or broken path. |
+| Relative `./mcp/dist/index.js` not found | Use an **absolute** `args` path to `index.js`, or open the correct folder as the project root. |
+| `logosdb_index_file` rejects a path | Path is outside cwd / `LOGOSDB_INDEX_ROOT`; use a path inside the project or set `LOGOSDB_INDEX_ROOT`. |
+| Search looks wrong after changing model | New embeddings must use a **fresh** `LOGOSDB_PATH` or new namespace; dimensions must match. |
+
+**Google Antigravity:** same stdio MCP pattern (`node` + local script, or `npx` + package). Step-by-step: [`mcp/README.md` — Google Antigravity](mcp/README.md#google-antigravity).
 
 ### Claude Code slash commands
 
 This repo ships **project slash commands** under [.claude/commands/](.claude/commands/) (in addition to [`.claude/mcp.json`](.claude/mcp.json) for the MCP server):
 
 | Command | Role |
 |---------|------|
-| `/index` | Index paths or text into a namespace (`commands/index.md`) |
+| `/index` | Index a **file or directory** into a namespace via `logosdb_index_file` (`commands/index.md`; arbitrary text uses the `logosdb_index` tool in chat) |
 | `/search` | Semantic search; optional ISO `ts_from` / `ts_to` on the MCP tool (`commands/search.md`) |
 | `/forget` | Delete by row `id` **or** by natural-language `query` (`commands/forget.md`) |
 
+### Agent instructions (`CLAUDE.md` and similar)
+
+The MCP server does not index the repository by itself: **the agent must call the tools** (or you rely on slash commands / hooks). To make LogosDB feel automatic without typing `/index` every time, add a block like the following to your project’s **`CLAUDE.md`** (or any instructions file your agent reads on every session). Adjust namespaces and paths to your repo.
+
+````markdown
+## LogosDB (semantic memory via MCP)
+
+The **logosdb** MCP server is configured. Data lives on disk under `LOGOSDB_PATH` (see `.claude/mcp.json`); it **persists across sessions**.
+
+**Namespaces:** Use separate namespaces for different concerns (e.g. `code` for `src/`, `docs` for `docs/`, `decisions` for short architectural notes). Search only the namespace that matches the user’s task.
+
+**When starting substantive work on this codebase:**
+1. If the user has not indexed recently and you need broad code context, call **`logosdb_index_file`** on the smallest useful path (e.g. `src/` or a package directory), not the whole monorepo unless asked.
+2. Before answering “where is X implemented?” or similar, call **`logosdb_search`** with a tight natural-language `query`, `namespace` set appropriately, and `top_k` between **3** and **8**. Do not paste entire trees into the chat—retrieve, then read only the cited files.
+3. For “what did we decide recently?” style questions, use **`logosdb_search`** with optional **`ts_from` / `ts_to`** (ISO 8601 inclusive bounds) on the `decisions` or `docs` namespace when timestamps matter.
+4. When the user states a durable fact worth remembering (API contract, policy, workaround), call **`logosdb_index`** into the right namespace with concise text (timestamps are stored automatically; optional **`metadata`** can label the source).
+
+**After large refactors or dependency upgrades:** Re-run **`logosdb_index_file`** on affected paths so search stays aligned with the tree.
+
+**Deletion:** Use **`logosdb_delete`** with **`id`** from a prior search hit, or with **`query`** + optional **`match_rank`** / **`search_top_k`** to remove a semantically matched row when the user asks to forget something.
+````
+
 ### Environment variables
 
 | Variable | Default | Description |
@@ -566,17 +657,68 @@ Voyage AI (`voyage-3`, dim=1024) is Anthropic's recommended cloud embedding mode
 
 ### Installing locally (without npx)
 
+**Option A — global CLI on your machine**
+
 ```bash
 npm install -g logosdb-mcp-server
 ```
 
-Then replace the `command`/`args` in `mcp.json` with:
+In `.claude/mcp.json`, point the server at the global binary:
+
+```json
+"logosdb": {
+  "command": "logosdb-mcp-server",
+  "args": [],
+  "env": { "LOGOSDB_PATH": "./.logosdb" }
+}
+```
+
+Ensure the directory containing the global npm binaries is on your `PATH` when Claude Code spawns the process (same shell you use for `npm install -g`).
+
+**Option B — project-local `node_modules` (no global install)**
+
+From your app repo:
+
+```bash
+npm install logosdb-mcp-server
+```
+
+Then use `npx` so the binary resolves from `./node_modules`:
+
+```json
+"logosdb": {
+  "command": "npx",
+  "args": ["-y", "logosdb-mcp-server"],
+  "env": { "LOGOSDB_PATH": "./.logosdb" }
+}
+```
+
+Omit `-y` if you prefer a fixed local install only. You can also call the entry script explicitly:
 
 ```json
-"command": "logosdb-mcp-server",
-"args": []
+"command": "node",
+"args": ["./node_modules/logosdb-mcp-server/dist/index.js"],
+"env": { "LOGOSDB_PATH": "./.logosdb" }
 ```
 
+**Option C — development build from a LogosDB clone**
+
+```bash
+cd mcp && npm install && npm run build
+```
+
+This repository’s checked-in [`.claude/mcp.json`](.claude/mcp.json) uses a **relative** path `./mcp/dist/index.js` after **`npm install` from the repo root** (workspace `prepare`). For **other** clients or if the process cwd is not the repo root, use an **absolute** path to `mcp/dist/index.js`:
+
+```json
+"logosdb": {
+  "command": "node",
+  "args": ["/absolute/path/to/logosdb/mcp/dist/index.js"],
+  "env": { "LOGOSDB_PATH": "./.logosdb" }
+}
+```
+
+The same `env` block (`LOGOSDB_PATH`, embedding variables) applies to every option. Restart Claude Code or reload MCP config after editing `.claude/mcp.json`.
+
 # Performance
 
 Here is a performance report from the included `logosdb-bench` program. The results are somewhat noisy, but should be enough to get a ballpark performance estimate.
@@ -585,6 +727,8 @@ Here is a performance report from the included `logosdb-bench` program. The resu
 
 We use databases with 1K, 10K, and 100K vectors. Each vector has 2048 dimensions (matching typical LLM embedding sizes). Vectors are L2-normalized random unit vectors.
 
+*(Report below was produced with an older `logosdb-bench` binary labeled 0.5.0; scaling and relative HNSW vs brute-force behavior are still representative of current builds.)*
+
     LogosDB:    version 0.5.0
     CPU:        Apple M-series (ARM64)
     Dim:        2048
@@ -647,8 +791,9 @@ LogosDB uses the same HNSW implementation as ChromaDB (hnswlib) but eliminates P
     examples/python/              Python usage examples
     pyproject.toml                Python build/config (scikit-build-core)
     third_party/hnswlib/          Vendored hnswlib (header-only)
+    package.json / package-lock.json   Root npm workspace (builds MCP for Claude Code)
     mcp/                          MCP server (logosdb-mcp-server npm package)
-    .claude/mcp.json              Example Claude Code MCP configuration
+    .claude/mcp.json              Claude Code MCP config (local `node ./mcp/dist/index.js`)
     .claude/commands/             Slash command prompts (/index, /search, /forget)
     CHANGELOG                     Release history
     LICENSE                       MIT license text

mcp/README.md

@@ -11,6 +11,79 @@ npm install -g logosdb-mcp-server
 
 Or run without installing via `npx -y logosdb-mcp-server`.
 
+## Claude Code: complete recipe
+
+These steps assume your **Claude Code project root** is the directory where you want `./.logosdb` (or your chosen `LOGOSDB_PATH`) to live. The MCP child process **`cwd`** is normally that same folder, so relative paths in `.claude/mcp.json` resolve there.
+
+### 1. Prerequisites
+
+- **Node.js** 18+ (`node -v`), **`npm`**, and for the recipes below **`npx`** on `PATH`.
+- **Claude Code** installed and authenticated.
+- Add **`.logosdb`** (or whatever you set in `LOGOSDB_PATH`) to **`.gitignore`** if you do not want vector data in version control.
+
+### 2. Install the package (pick one)
+
+**Published server (typical):** no project `package.json` is required if Claude Code will run `npx` for you. Optional registry check:
+
+```bash
+npm view logosdb-mcp-server version
+```
+
+Alternatively add a dependency:
+
+```bash
+npm install logosdb-mcp-server
+```
+
+**Develop from a LogosDB git clone:** from the monorepo root run `npm install` so `mcp/dist/index.js` is built; then point `mcp.json` at that file with `node` (see the main [README — Claude Code recipe](https://github.com/jose-compu/logosdb/blob/main/README.md#claude-code-complete-recipe)).
+
+### 3. Create `.claude/mcp.json`
+
+In your **project root**, create `.claude/mcp.json` (or merge into **`~/.claude.json`** for all projects) with a `logosdb` entry.
+
+**Recommended (always run the published server):**
+
+```json
+{
+  "mcpServers": {
+    "logosdb": {
+      "command": "npx",
+      "args": ["-y", "logosdb-mcp-server"],
+      "env": {
+        "LOGOSDB_PATH": "./.logosdb"
+      }
+    }
+  }
+}
+```
+
+**Project-local install (pin a version in `package.json`):** same `mcpServers` block, or point `node` at `./node_modules/logosdb-mcp-server/dist/index.js` with empty `args` — see [Configure](#configure).
+
+**Optional env:** Ollama, OpenAI, Voyage, chunk size, and index root are in [Configure](#configure) and [Environment variables](#environment-variables).
+
+### 4. Path confinement for indexing
+
+`logosdb_index_file` only accepts paths under **`process.cwd()`** or **`LOGOSDB_INDEX_ROOT`**. Read [Path confinement (`logosdb_index_file`)](#path-confinement-logosdb_index_file) before indexing parent directories or using symlinks.
+
+### 5. Restart and verify
+
+- Restart **Claude Code** or reload MCP after editing JSON.
+- Ask the agent to run **`logosdb_list`**. If the server fails to spawn, run the same `command` + `args` in a shell from your project root and fix errors (missing Node, network for `npx`, etc.).
+
+### 6. Use it
+
+- Ask in natural language to index `src/` (or a file), search semantically, or store a short decision via **`logosdb_index`**.
+- **Slash commands:** copy [`.claude/commands/`](https://github.com/jose-compu/logosdb/tree/main/.claude/commands) from the LogosDB repo into your project for `/index`, `/search`, `/forget` (optional).
+- **Agent habits:** add a `CLAUDE.md` snippet so the agent indexes and searches without reminders — see the main [README — Agent instructions](https://github.com/jose-compu/logosdb/blob/main/README.md#agent-instructions-claudemd-and-similar).
+
+### 7. Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `npx` cannot download or run the package | Check network, Node version, and corporate proxy; try `npm install logosdb-mcp-server` + `node ./node_modules/logosdb-mcp-server/dist/index.js` in `args` via `node` command. |
+| Wrong embedding size / garbage search | Use one backend and dimension per namespace; use a fresh `LOGOSDB_PATH` or new namespace when changing models ([Environment variables](#environment-variables)). |
+| Path rejected on index | Stay inside cwd or set `LOGOSDB_INDEX_ROOT` to an absolute allowed directory. |
+
 ## Configure
 
 ### Default: local embeddings (Transformers.js)

mcp/package.json

@@ -8,6 +8,7 @@
     "logosdb-mcp-server": "dist/index.js"
   },
   "scripts": {
+    "prepare": "npm run build",
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",