---
name: nano-brain
description: Persistent memory + code intelligence for AI coding agents. Hybrid search (BM25 + vector + RRF), cross-session recall, symbol graph analysis, impact checks, OpenCode/Claude Code session harvesting. Use when you need to recall prior decisions, search across sessions/codebase, trace symbol callers/callees, or persist long-term context.
compatibility: OpenCode, Claude Code, any MCP-aware agent
metadata:
  author: nano-step
  version: 3.2.0
  upstream: https://github.com/nano-step/nano-brain
---

# nano-brain

Persistent memory + code-intel daemon. Agents talk to it via **MCP** — streamable HTTP at `/mcp` on the daemon. HTTP is available as a fallback for scripts and integration tests.

This file documents the MCP surface. Deeper references:

- `@references/http-api.md` — full HTTP endpoint reference (for scripts, tests, dashboards)
- `@references/code-intelligence.md` — symbol graph (`memory_graph`, `memory_impact`, `memory_trace`, `memory_symbols`)
- `@references/config-reference.md` — daemon `config.yml` schema + env vars

(load these only when you need them — most agent workflows live in this file.)

## When to call which tool

| You need to... | Tool | Why |
|---|---|---|
| Recall past work on a topic | `memory_query` | Hybrid (BM25 + vector + recency) — best default |
| Find exact string (error msg, fn name) | `memory_search` | BM25 — fastest, no rerank |
| Explore fuzzy concept | `memory_vsearch` | Vector only — semantic match |
| Save a decision/lesson | `memory_write` | Persists for future sessions |
| Catch up at session start | `memory_wake_up` | Recent docs + active collections + stats |
| Fetch one doc by ID/path | `memory_get` | Full content + metadata |
| Check daemon health/queue | `memory_status` | PG + embed queue + harvester |
| Trace symbol callers/callees | `memory_graph` | 1-hop neighbors |
| Risk-check before refactor | `memory_impact` | Reverse-impact BFS, depth 1-3 |
| Walk call chain | `memory_trace` | Forward walk with cycle detect, depth 1-10 |
| Find a symbol by name/kind | `memory_symbols` | Function/type/method/interface search |
| List all tags | `memory_tags` | Tag inventory |
| Force re-embed | `memory_update` | Re-queues workspace chunks |

## MCP tool schemas

Connect: streamable HTTP at `/mcp` on the daemon. Container agents use `http://host.docker.internal:3100/mcp`.

Every tool takes a `workspace` string (the SHA-256 hash returned by `POST /api/v1/init`). Listed required fields are in the `required` array of the InputSchema.

### memory_query — hybrid search (DEFAULT)
```
required: workspace, query
optional: max_results (int, default 10, capped at 100)
          include_content (bool, default false) — opt-in full chunk text
          cursor (string) — pagination token from previous response.next_cursor
returns:  {results: [{id, title, snippet, score, tags, collection, source_path, workspace_hash, document_id, created_at, updated_at}], total, query_ms, next_cursor?}
```
Each result includes a `snippet` (≤500 chars, UTF-8 safe). The full `content` field is OMITTED by default — pass `include_content: true` to include it, or call `memory_get` for one full document. `next_cursor` is present only when more results exist beyond the current page.

### memory_search — BM25 keyword
```
required: workspace, query
optional: max_results (capped 100), tags (array of strings — AND filter)
          include_content (bool, default false), cursor (string)
returns:  same shape as memory_query (snippet-only by default)
```
Note: tags filter is conjunctive (chunk must have ALL listed tags).

### memory_vsearch — vector semantic
```
required: workspace, query
optional: max_results (capped 100), include_content (bool), cursor (string)
returns:  same shape as memory_query (snippet-only by default)
```
Slower than BM25 (embedding round-trip); best for "concept similar to…" queries where exact words don't match.

### Pagination & include_content (since #358 / v2026.6.x)

All three search tools share one response envelope. Paginate with the opaque `cursor` returned in `next_cursor` — pass the SAME `query` text on every page (server validates a hash to prevent cross-query cursor reuse → error `"cursor query mismatch"`).

```
# Browse 30 days of bug fixes incrementally — no payload bombs
memory_search(workspace=ws, query="fix bug", max_results=5)
  → {results: [...5...], total: 47, query_ms: 12, next_cursor: "eyJv..."}
memory_search(workspace=ws, query="fix bug", max_results=5, cursor="eyJv...")
  → next 5 results...
```

Need the FULL text of one specific hit? Call `memory_get(workspace, path="#<id-from-result>")` — that tool is the canonical full-content fetch and supports `start_line`/`end_line` slicing. Pass `include_content: true` to a search tool only when you genuinely need full text for ALL results in one shot (rare; inflates response 5–50×).

### Time-range filters (since #360)

Agents asking time-bounded questions ("what bugs have we fixed in the last 30 days?") can push the filter directly to the database — no client-side `updated_at` filtering, no extra pagination loops.

All three search tools (`memory_query`, `memory_search`, `memory_vsearch`) accept four optional parameters:

| Parameter | Type | Description | Example |
|---|---|---|---|
| `created_after` | string | Restrict to docs created after this point | `"30d"`, `"2026-05-01T00:00:00Z"` |
| `created_before` | string | Restrict to docs created before this point | `"7d"`, `"2026-06-01T00:00:00Z"` |
| `updated_after` | string | Restrict to docs updated after this point | `"1w"`, `"720h"` |
| `updated_before` | string | Restrict to docs updated before this point | `"2mo"`, `"2026-04-01T00:00:00Z"` |

Multiple filters combine with AND semantics. Omitting all four leaves behavior identical to pre-#360.

#### Accepted formats

**Preferred for LLM agents: compute the absolute date client-side and pass RFC3339.** You already know today's date from your system context — do the subtraction yourself (`2026-06-03 minus 30 days = 2026-05-04T00:00:00Z`) and pass the result. This avoids the 30-day-month / 365-day-year approximation in relative durations and produces stable, auditable queries. Relative durations exist primarily for human-typed CLI use (`nano-brain search --updated-after=30d`).

- **RFC3339 absolute** (preferred): `"2026-05-04T12:00:00Z"` — timezone required; future timestamps accepted (explicit agent choice)
- **Go-style duration**: `"720h"`, `"30m"`, `"1h30m"` — subtracted from now
- **Humanish relative**: `"30d"`, `"1w"`, `"2mo"`, `"1y"` — units: `s`, `m`, `h`, `d`, `w`, `mo`, `y` (approximate — see caveat below)

#### Rejected inputs (with error messages)

```
"2026-05-04"      → invalid timestamp or duration "2026-05-04": not a valid RFC3339 timestamp...
                    (fix: "2026-05-04T00:00:00Z")

"-30d"            → invalid timestamp or duration "-30d": duration must be positive, got -720h0m0s
"0d"              → invalid timestamp or duration "0d": duration must be positive, got 0s
"-720h"           → invalid timestamp or duration "-720h": duration must be positive, got -720h0m0s

"banana"          → invalid timestamp or duration "banana": not a valid RFC3339 timestamp, Go duration,
                    or humanish duration (e.g., '30d', '1w')
"30x"             → same (unknown unit)
```

Validation runs before any database call. The error names the offending parameter and the rejected value.

#### Rough-relative caveat

`1mo` = 30 days exactly. `1y` = 365 days exactly. These are approximate — not calendar-aware month/year arithmetic. For queries that require calendar precision ("since the start of April"), pass an RFC3339 timestamp instead.

#### Worked examples

```
# memory_search — find bug-fix discussions from the last 30 days
# Preferred (LLM computes the cutoff):
memory_search(workspace=<hash>, query="bug fix", updated_after="2026-05-04T00:00:00Z")
# Or relative (works but less precise):
memory_search(workspace=<hash>, query="bug fix", updated_after="30d")

# memory_query — hybrid search for design docs created since May 1, 2026
memory_query(workspace=<hash>, query="design", created_after="2026-05-01T00:00:00Z")

# memory_vsearch — semantic similarity, only documents from the last week
memory_vsearch(workspace=<hash>, query="rate limiting strategy", updated_after="2026-05-27T00:00:00Z")
```

#### Pagination interaction

The cursor encodes ALL filter values (query + tags + time-range raw strings). Paginating with different filter values returns `"cursor invalidated, restart pagination"`. To page through a filtered result set, pass the SAME filter values on every subsequent call:

```
memory_search(workspace=<hash>, query="bug fix", updated_after="30d", max_results=5)
  → next_cursor: "eyJv..."
memory_search(workspace=<hash>, query="bug fix", updated_after="30d", max_results=5, cursor="eyJv...")
  → next page, same filtered window
```

### memory_get — fetch one doc
```
required: workspace, path
optional: start_line (1-indexed inclusive), end_line (1-indexed inclusive)
path:     either source_path (e.g. memory://foo/bar) OR #<uuid> form
returns:  {id, title, content, source_path, collection, tags, workspace_hash, supersedes_id?, created_at, updated_at}
```
Source: `internal/mcp/tools.go:417-506`, `internal/server/handlers/get_document.go:21-37`. Use `start_line`/`end_line` for huge docs to avoid loading megabytes.

### memory_write — persist a decision
```
required: workspace (must be registered via /api/v1/init — workspace="all" is REJECTED, issue #238), content (max 5MB)
optional: title, tags (array), collection (default "memory"), source_path, metadata (object), supersedes (#<uuid> or source_path of doc this replaces)
returns:  {id, hash, collection, workspace_hash, chunk_count, warning?}
```
Source: `internal/mcp/tools.go:508-680`. Tags convention: `decision`, `lesson`, `summary`, `bug`, `gotcha`, plus an area tag (`auth`, `queue`, etc.). Same `source_path` upserts (replaces) the existing doc.

### memory_wake_up — session-start briefing
```
required: workspace
optional: limit (default 10, capped 50)
returns:  {summary, recent_memories: [{id, title, snippet, tags, date}], active_collections: [{name, document_count, last_updated}], stats: {total_documents, total_chunks, last_activity}}
```
Source: `internal/mcp/tools.go:791-914`, `internal/server/handlers/wakeup.go:22-52`. Call first thing after registering a workspace; the `summary` field gives the agent a one-paragraph orientation.

### memory_status — daemon health
```
required: (none)
returns:  {pg_status, migration_version, embedding_queue_depth, active_provider, workspace_count, queue_depth, queue_capacity, queue_status, queue_pending, harvester_status: {...}}
```
Source: `internal/mcp/tools.go:731-763`, `internal/server/handlers/health.go:111-122`. Check `queue_pending` if `memory_search` returns nothing — chunks may still be embedding.

### memory_graph — 1-hop symbol neighbors
```
required: workspace, node ("internal/x.go" OR "internal/x.go::F" OR absolute equivalent)
optional: direction ("out" | "in" | "both", default "out"), edge_type ("calls" | "imports" | "contains" | empty for all), paths ("absolute" default | "relative" to save tokens)
returns:  {node, direction, edges: [{source, target, edge_type}]}
```
Source: `internal/mcp/tools.go:1214-1308`. Requires prior `reindex` to populate the graph. Node accepts workspace-relative or absolute paths (resolved server-side). Set `paths: "relative"` to receive workspace-stripped paths in the response — saves ~55 chars × N edges per call.

### memory_impact — reverse impact BFS
```
required: workspace, node
optional: edge_type, max_depth (1-3, server-clamped, default 1), paths ("absolute" default | "relative")
returns:  {node, impacted: [{node, depth, edge_type}]}
```
Source: `internal/mcp/tools.go:1395-1469`. Use before refactor — `impacted` is the set of nodes that would break if `node` changes. Same relative/absolute path support as `memory_graph`.

### memory_trace — forward call chain
```
required: workspace, node
optional: max_depth (1-10, server-clamped, default 5), paths ("absolute" default | "relative")
returns:  {entry, chain: [{node, depth, via}]}
```
Source: `internal/mcp/tools.go:1316-1393`. Walks outgoing edges with cycle detection. Use to understand "what does this entry point eventually call?". Same relative/absolute path support as `memory_graph`.

### memory_symbols — symbol search
```
required: workspace
optional: query (substring filter), kind ("function" | "method" | "type" | "interface" | "struct" | "const" | "var"), limit (default 50, capped 200)
returns:  {symbols: [{name, kind, language, signature, source_path}], count}
```
Source: `internal/mcp/tools.go:1159-1223`.

### memory_tags — tag inventory
```
required: workspace
returns:  array of tag/collection summaries (see tool schema)
```
Source: `internal/mcp/tools.go:682-729`.

### memory_update — force re-embed
```
required: workspace (must be registered)
returns:  count of chunks re-queued
```
Source: `internal/mcp/tools.go:765-789`. Rare — only useful after switching embedding model or fixing corrupt embeddings.

## Recipes

### R1 — Session start
```
1. memory_wake_up(workspace, limit=8)      // briefing + recent docs
2. memory_query(workspace, query="<task topic>")  // anything we learned about this?
```
Costs ~500 tokens; saves much more by preventing redundant exploration.

### R2 — Recall before grep
nano-brain finds matches in past sessions, prior commits, docs. Grep finds matches in current files. Always recall first (cheap, ~200 tokens) then grep for exact code locations.

| Need | Call |
|---|---|
| "Did we hit this error before?" | `memory_search("ECONNREFUSED redis")` |
| "How did we handle rate limiting?" | `memory_vsearch("rate limiting strategy")` |
| "What did we decide about X?" | `memory_query("X decision")` |

### R3 — Pre-refactor impact check
```
memory_impact(workspace, node="/path/file.go::Symbol", edge_type="calls", max_depth=2)
```
Read the `impacted` array — count > 10 means HIGH risk, treat as "needs review."

### R4 — Persist a decision (end of session)
```
memory_write(
  workspace,
  content="## Decision: …\n- Why: …\n- Trade-off: …\n- Files: …",
  tags=["decision", "architecture", "<area>"],
  collection="memory"
)
```
Tags are how future-you filters. Be consistent: `decision`, `lesson`, `summary`, `bug`, `gotcha`, plus an area.

### R5 — Triage many results
For broad queries with 10+ hits, scan via low max_results first, then expand the relevant ones:
```
1. memory_query(workspace, query="…", max_results=5)  // top hits only
2. memory_get(workspace, path="#<uuid-from-top-hit>")  // full content of the chosen one
```

### R6 — Cross-workspace recall
There is no `workspace="all"` for write paths (rejected for safety per #238). For READ paths, switch workspaces in a loop:
```
for ws in $registered_workspaces:
  memory_query(workspace=ws, query="<topic>")
```
Or use HTTP `GET /api/v1/workspaces` to list hashes, then iterate.

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| `cannot connect to daemon` | nano-brain not running on host | Operator action — start the daemon on the host (out of scope for agents). Then re-resolve MCP URL via `NANO_BRAIN_MCP_URL`. |
| `workspace_not_found` (HTTP 404) | Workspace hash not in DB (#309 fix) | `POST /api/v1/init {root_path: …}` first |
| `workspace_required` (HTTP 400) | Empty workspace field | Always pass `workspace` arg/body field |
| `memory_search` returns 0 | Embedding queue still working | Check `memory_status.queue_pending`; new docs need embed before vector search hits them. BM25 lands immediately. |
| `chunk truncated before embedding` warns flood log (pre-v2026.6.0202) | Chunker emitted oversize chunks | Upgrade ≥v2026.6.0202 — #297 + #300 align chunker default with embed budget |
| Title-only query returns 0 (pre-v2026.6.0201) | BM25 indexed only chunk content | Upgrade ≥v2026.6.0201 — migration 13 adds title to tsvector (#305) |
| `memory_query` returns score=0 + empty title (pre-v2026.6.0107) | MCP serialization missing JSON tags | Upgrade ≥v2026.6.0107 — #303 added snake_case tags to search.Result |
| New workspace registered but not indexing (pre-v2026.6.0108) | File watcher loaded list once at startup | Upgrade ≥v2026.6.0108 — #308 wires hot-register signal |

## Connection details (rare — most MCP clients handle this for you)

The daemon is expected to be already running on the host. Agents connect via the registered MCP server.

**MCP URL** — set `NANO_BRAIN_MCP_URL` to override the resolved URL:
- Container agents (default): `http://host.docker.internal:3100/mcp`
- Bare-metal / host agents: `http://localhost:3100/mcp`

| Layer | URL | When |
|---|---|---|
| MCP (default) | `http://host.docker.internal:3100/mcp` from container, `http://localhost:3100/mcp` from host | Agent tools |
| HTTP API | Same host, no `/mcp` suffix | See `@references/http-api.md` |

For HTTP / config deep dives: load the matching `@references/` file.

## Troubleshooting

| Symptom | Fix |
|---|---|
| MCP tool calls fail with connection error | Operator action — daemon is not running on the host. Out of scope for agents; surface the error to the user. |
| MCP URL wrong in container | Export `NANO_BRAIN_MCP_URL=http://host.docker.internal:3100/mcp` before starting agent |
| MCP URL wrong on bare-metal | Export `NANO_BRAIN_MCP_URL=http://localhost:3100/mcp` |
| MCP tools return `workspace_not_found` | Call `memory_workspaces_resolve` first to resolve the project path to a registered workspace hash; if `registered: false`, the project has not been initialized. |