nano-brain weekly downloads statistics

nano-brain

Built for agents. Not humans.

Agent-oriented memory and code intelligence over MCP. AI agents don't read docs — they call tools. nano-brain gives them structured context, symbol lookup, call-chain tracing, and change-impact analysis across sessions and repos.

---

What it is

nano-brain is an infrastructure layer between your AI agent and your code. It solves two problems agents have:

1. Session amnesia — agents forget everything when a session ends. nano-brain harvests, indexes, and retrieves past sessions and saved decisions.
2. Codebase blindness — agents can't cheaply trace dependencies, measure blast radius, or map an execution path. nano-brain builds a code graph and exposes it as MCP tools.

Self-hosted (Go binary + PostgreSQL), works with any MCP client (Claude Code, OpenCode, Cursor, …), and returns structured results — not raw file bytes.

---

Install

# Recommended — one-line installer (no Node.js needed): downloads the prebuilt
# binary for your platform from GitHub Releases and verifies its SHA-256.
curl -fsSL https://raw.githubusercontent.com/nano-step/nano-brain/master/install.sh | bash

# Or via npm (handy if you're already in a JS/agent toolchain)
npm install -g @nano-step/nano-brain

# Or build from source
CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain

Prefer to read the installer first? curl -fsSL -o install.sh https://raw.githubusercontent.com/nano-step/nano-brain/master/install.sh && less install.sh && bash install.sh.

Start

# One command — the interactive wizard provisions PostgreSQL (Docker or remote URL),
# configures embeddings, starts the server, registers this project, and wires up your MCP client.
nano-brain init

Manual, per-step setup (VPS / team / no Docker / Windows): docs/SETUP_AGENT.md.

Connect your agent

Add to your MCP client config:

{
  "mcp": {
    "nano-brain": { "type": "remote", "url": "http://localhost:3100/mcp" }
  }
}

Bind a default workspace by appending ?workspace=<name-or-hash> to the URL (e.g. …/mcp?workspace=my-project) so tool calls can omit the workspace argument. An explicit workspace argument always overrides it; the value must be a name or full hash (not "all"). Run nano-brain workspaces list to see registered names/hashes.

For OpenCode, you can bootstrap the current workspace with npx @nano-step/nano-brain init -- opencode. It installs a /nano-brain slash command that keeps the workspace config local at .nanobrain/config.yml.

---

The agent workflow

A cold agent should follow this order — it maps 1:1 to the tools:

1. Orient — memory_wake_up for a workspace briefing (recent activity, collections, stats).
2. Locate the workspace — memory_workspaces_resolve(path) returns a deterministic hash and whether it's registered. Registering the repo root also covers its subdirectories, so resolve the root, not a single sub-repo.
3. Understand — memory_query (hybrid, best for natural-language questions), memory_search (exact identifiers/errors), or memory_vsearch (fuzzy concepts). Search returns 500-char snippets; fetch full text with memory_get only for the hits you keep.
4. Navigate code — memory_symbols to find a definition (no indexing needed), then memory_graph / memory_trace for call chains and memory_flow for an HTTP route's execution.
5. Before a risky edit — memory_impact(node, direction="in") for the blast radius (who calls / imports this).
6. Persist — memory_write to save a decision, lesson, or handoff for the next session.

wake_up → resolve ─▶ query / search / symbols ─▶ graph / trace / flow / impact ─▶ (edit) ─▶ write

---

MCP tools (18)

Search & recall

Tool	Use it for
memory_query	Hybrid BM25 + vector + RRF + recency — default first tool for broad questions
memory_search	Exact keyword/BM25 — error strings, identifiers, config keys, channel/topic names
memory_vsearch	Vector similarity — fuzzy concepts (best on single-concept queries)
memory_get	Fetch full content (or a line range) for one known document/symbol
memory_write	Persist a decision/lesson/handoff (supports supersedes)
memory_ticket	All sessions tagged with a ticket ID (e.g. PROJ-1234) across the workspace
memory_wake_up	Session-start briefing: recent memories, active collections, stats
memory_tags	List collections and document counts

Code intelligence

Tool	Use it for
memory_symbols	Find a function/type/interface/const by name (reads the filesystem — no indexing required)
memory_graph	One-hop neighbors: direct callers/callees, imports, containment
memory_trace	Downstream call chain from an entry symbol
memory_impact	Reverse blast radius before an edit: who calls/imports this
memory_flow	HTTP route execution flow (middleware → handler → downstream), Mermaid/sequence/JSON
memory_flowchart	Control-flow graph of a single function (branches, loops, returns)

Workspace & ops…