@nano-step/nano-brain 2026.5.25-beta.31 → 2026.5.30

package/README.md

@@ -111,7 +111,9 @@ search:
 
 harvester:
   opencode:
-    session_dir: ""             # e.g., ~/.local/share/opencode/storage
+    db_root: ""                 # e.g., ~/.ai-sandbox/opencode-dbs (multi-DB, highest priority)
+    db_path: ""                 # e.g., ~/.local/share/opencode/opencode.db (single DB)
+    session_dir: ""             # e.g., ~/.local/share/opencode/storage (legacy JSON)
   claudecode:
     enabled: false
     session_dir: ""
@@ -130,16 +132,68 @@ telemetry:
 logging:
   level: info
   file: ""                      # empty = stdout only
+
+summarization:
+  enabled: false                # set to true to generate LLM summaries of harvested sessions
+  provider_url: ""              # OpenAI-compatible endpoint, e.g. https://ai-proxy.example.com/v1
+  api_key: ""                   # or set NANO_BRAIN_SUMMARIZE_API_KEY env var
+  model: "nano-brain"           # model name passed to the provider
+  max_tokens: 8000              # max tokens per LLM completion
+  concurrency: 3                # parallel map-phase LLM calls
+```
+
+### Session Summarization
+
+When `summarization.enabled: true`, nano-brain automatically generates structured markdown summaries of each harvested session using an OpenAI-compatible LLM provider. Summaries are:
+
+- Stored in PostgreSQL under collection `session-summary` for semantic search via the standard query/vsearch API (PG is the source of truth)
+- Idempotent — unchanged sessions are skipped; re-harvested sessions overwrite old summaries
+
+> **Note**: as of `harvest-summary-only` (May 2026), summaries are no longer written to disk as `.md` files. The legacy `output_dir` YAML key is silently ignored for backward compat. Any pre-existing files under `~/.nano-brain/summaries/` are stale artifacts and can be safely deleted.
+
+**Quick setup with ai-proxy:**
+
+```yaml
+summarization:
+  enabled: true
+  provider_url: "https://ai-proxy.example.com/v1"
+  api_key: ""           # set NANO_BRAIN_SUMMARIZE_API_KEY instead
+  model: "claude-sonnet-4-5"
+  max_tokens: 8000
+  concurrency: 3
 ```
 
+Or via environment variable:
+
+```bash
+export NANO_BRAIN_SUMMARIZE_API_KEY="sk-..."
+```
+
+Large sessions (100K+ tokens) are handled via map-reduce chunking — no session is too large.
+
 ### Environment Variables
 
 | 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_STORAGE_DIR` | OpenCode session directory |
-| `NANO_BRAIN_*` | Override any config (e.g., `NANO_BRAIN_SERVER_PORT=3100`) |
+| `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 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
 
@@ -151,6 +205,7 @@ logging:
 | 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 |
@@ -171,8 +226,11 @@ 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 |
 | POST | `/api/v1/wake-up` | Workspace briefing with session_dir |
 
 ### MCP Endpoints
@@ -188,12 +246,19 @@ 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 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 |
@@ -204,7 +269,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 |
 |------|-------------|
@@ -217,6 +282,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.25-beta.31",
+  "version": "2026.5.30",
   "description": "Persistent memory and code intelligence for AI coding agents",
   "bin": {
     "nano-brain": "npm/run.js"