@nano-step/nano-brain 2026.5.2903 → 2026.5.3006

package/README.md

@@ -175,13 +175,25 @@ Large sessions (100K+ tokens) are handled via map-reduce chunking — no session
 
 | Variable | Description |
 |----------|-------------|
+| `NANO_BRAIN_CONFIG` | Path to YAML config file (12-factor; useful in Docker/k8s). Precedence: `--config` flag > `NANO_BRAIN_CONFIG` > `~/.nano-brain/config.yml`. Leading/trailing whitespace is stripped. If the env-pointed file does not exist, a `WARNING:` is printed to stderr and defaults are used (operator can spot typos). |
 | `DATABASE_URL` | PostgreSQL connection string |
 | `VOYAGE_API_KEY` | Voyage AI API key |
 | `OPENCODE_DB_ROOT` | OpenCode per-project DB root directory (multi-DB mode) |
 | `OPENCODE_DB_PATH` | OpenCode single SQLite database path |
 | `OPENCODE_STORAGE_DIR` | OpenCode session directory (legacy) |
 | `NANO_BRAIN_SUMMARIZE_API_KEY` | API key for the summarization LLM provider |
-| `NANO_BRAIN_*` | Override any config (e.g., `NANO_BRAIN_SERVER_PORT=3100`) |
+| `NANO_BRAIN_*` | Override any config field (e.g., `NANO_BRAIN_SERVER_PORT=3100`) |
+
+**Docker example** — run the server in a container against a host PostgreSQL:
+
+```bash
+# /path/to/container-config.yml uses host.docker.internal for DB/Ollama
+docker run -d \
+  -e NANO_BRAIN_CONFIG=/etc/nano-brain/config.yml \
+  -v /path/to/container-config.yml:/etc/nano-brain/config.yml:ro \
+  -p 3100:3100 \
+  nano-brain:latest
+```
 
 ## REST API
 
@@ -193,6 +205,7 @@ Large sessions (100K+ tokens) are handled via map-reduce chunking — no session
 | GET | `/api/status` | Server status with version, uptime, workspace stats |
 | POST | `/api/v1/init` | Register workspace |
 | GET | `/api/v1/workspaces` | List all workspaces (with doc counts) |
+| DELETE | `/api/v1/workspaces/:hash` | Permanently delete a workspace + cascade docs/chunks/embeddings |
 | GET | `/api/v1/wake-up` | Workspace briefing |
 | POST | `/api/harvest` | Trigger session harvesting |
 | POST | `/api/reload-config` | Hot-reload configuration |
@@ -213,6 +226,8 @@ Workspace is passed in the JSON body for POST, query param for GET.
 | PUT | `/api/v1/collections/:name` | Rename collection |
 | DELETE | `/api/v1/collections/:name` | Remove collection |
 | GET | `/api/v1/tags` | List tags with counts |
+| POST | `/api/v1/get` | Get single document by source_path or id |
+| POST | `/api/v1/multi-get` | Batch fetch documents by paths or ids |
 | POST | `/api/v1/reindex` | Queue reindex (202) |
 | POST | `/api/v1/update` | Queue update (202) |
 | POST | `/api/v1/summarize` | Trigger LLM summarization of harvested sessions |
@@ -231,13 +246,20 @@ Workspace is passed in the JSON body for POST, query param for GET.
 |---------|-------------|
 | `nano-brain` (no args) | Start HTTP server (default: port 3100) |
 | `nano-brain init --root=<path>` | Register workspace |
+| `nano-brain workspaces list` | List registered workspaces with doc counts |
+| `nano-brain workspaces remove --workspace=<hash> [--dry-run\|--force]` | Permanently delete a workspace + all its documents/chunks/embeddings |
 | `nano-brain write` | Write document via CLI |
-| `nano-brain query` | Hybrid search |
-| `nano-brain search` | BM25 keyword search |
-| `nano-brain vsearch` | Vector similarity search |
+| `nano-brain query [--scope=all] [--tags=t1,t2]` | Hybrid search (BM25 + vector + RRF + recency) |
+| `nano-brain search [--scope=all] [--tags=t1,t2]` | BM25 keyword search |
+| `nano-brain vsearch [--scope=all] [--tags=t1,t2]` | Vector similarity search |
+| `nano-brain wake-up --workspace=<hash>` | Workspace briefing (collections, stats, recent memories) |
+| `nano-brain get <source_path\|uuid> --workspace=<hash>` | Fetch a single document by source_path or UUID |
+| `nano-brain tags --workspace=<hash>` | List all tags with document counts |
+| `nano-brain multi-get --workspace=<hash> --paths=p1,p2` | Fetch multiple documents in one round-trip |
 | `nano-brain collection add\|remove\|list` | Manage collections |
 | `nano-brain harvest` | Trigger session harvesting |
 | `nano-brain cleanup-stale-raw [--dry-run]` | Delete pre-#192 raw OpenCode session docs superseded by summaries |
+| `nano-brain cleanup-orphan-workspaces [--dry-run]` | Delete documents/chunks under workspace_hash values not registered in `workspaces`. Run BEFORE migration 00011 (issue #238). |
 | `nano-brain bench generate\|run\|compare\|stress` | Benchmarking suite |
 | `nano-brain db:migrate` | Run pending goose migrations |
 | `nano-brain db:migrate --from-v1 <path>` | Import V1 SQLite data |
@@ -248,7 +270,7 @@ Workspace is passed in the JSON body for POST, query param for GET.
 
 ## MCP Tools
 
-nano-brain exposes 9 tools via MCP (Model Context Protocol):
+nano-brain exposes 13 tools via MCP (Model Context Protocol):
 
 | Tool | Description |
 |------|-------------|
@@ -261,6 +283,10 @@ nano-brain exposes 9 tools via MCP (Model Context Protocol):
 | `memory_status` | Server and embedding status |
 | `memory_update` | Trigger re-embedding |
 | `memory_wake_up` | Workspace briefing |
+| `memory_graph` | Knowledge graph view (module → function → dep) |
+| `memory_trace` | Call chain trace from entry point |
+| `memory_impact` | Cross-file change impact analysis |
+| `memory_symbols` | Symbol search (functions, types, constants) |
 
 ### MCP Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-step/nano-brain",
-  "version": "2026.5.2903",
+  "version": "2026.5.3006",
   "description": "Persistent memory and code intelligence for AI coding agents",
   "bin": {
     "nano-brain": "npm/run.js"