nano-brain

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.