nano-brain

Persistent memory and code intelligence for AI coding agents.

What It Does

nano-brain is a persistent memory server for AI coding agents that solves session amnesia. It automatically ingests AI sessions, notes, and codebase files, indexes everything with hybrid search (BM25 + pgvector), and serves memories via MCP tools and REST API. Built in Go with PostgreSQL — single static binary, zero CGO dependencies.

Use Cases

Multi-machine developer (primary use case)

You work on your office PC, home machine, and personal laptop — each with a different Claude Code or OpenCode session. Without shared memory, your AI agent forgets everything between machines.

Deploy nano-brain on a VPS (or any always-on server) with a PostgreSQL instance. Every session you run on any machine gets harvested and indexed there. When you switch machines, your agent picks up exactly where you left off — decisions, context, code knowledge, all there.

Office PC ──┐
             ├──► nano-brain on VPS ──► shared PostgreSQL
Home Mac ───┘

Persistent AI agent memory

AI agents forget everything when the session ends. nano-brain gives them durable, searchable memory across sessions — decisions made, patterns discovered, code written — so they don't repeat work or ask the same questions twice.

Code intelligence for large codebases

nano-brain builds a symbol graph of your codebase: functions, types, dependencies, call chains. Agents can ask "what breaks if I change this function?" (memory_impact) or "trace the call chain from this entry point" (memory_trace) — across files, across sessions.

Notes and documentation search

Write structured notes, ADRs, or decision records into nano-brain. Hybrid search (BM25 + semantic) retrieves them by keyword or concept. Agents can surface the right context without you having to remember where you put it.

Key Features

• Hybrid search — BM25 full-text + pgvector HNSW cosine similarity + RRF fusion + recency decay
• 9 MCP tools — query, search, vsearch, get, write, tags, status, update, wake_up
• Session harvesting — auto-ingest OpenCode and Claude Code sessions
• File watcher — fsnotify-based directory monitoring with debounce
• Content-addressed storage — SHA-256 deduplication
• Heading-aware markdown chunking
• Multi-workspace isolation with per-workspace data
• Config hot-reload — POST /api/reload-config
• V1 migration — import from SQLite (pure Go, no CGO)
• Benchmarking suite — generate, run, compare, stress
• Search telemetry — local-only, 90-day retention, non-blocking

Prerequisites

• Go 1.23+ (building from source) OR pre-built binary
• PostgreSQL 17 with pgvector 0.8.2 extension
• Embedding provider: Ollama (default, local) or Voyage AI

Quick Start

Option A: Via MCP (recommended for AI agents)

Add to your MCP client config — no install required if the server is already running:

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

Option B: Install globally (fast, no cold-start overhead)

npm install -g @nano-step/nano-brain

# Start PostgreSQL + pgvector
docker run -d --name nanobrain-pg -p 5432:5432 \
  -e POSTGRES_USER=nanobrain -e POSTGRES_PASSWORD=nanobrain -e POSTGRES_DB=nanobrain_dev \
  pgvector/pgvector:pg17

# Start Ollama + pull embedding model
ollama pull nomic-embed-text

# Check prerequisites
nano-brain doctor

# Start server
nano-brain serve -d

Option C: Via npx (no install, slower cold-start)

# Start PostgreSQL + pgvector
docker run -d --name nanobrain-pg -p 5432:5432 \
  -e POSTGRES_USER=nanobrain -e POSTGRES_PASSWORD=nanobrain -e POSTGRES_DB=nanobrain_dev \
  pgvector/pgvector:pg17

# Start Ollama + pull embedding model
ollama pull nomic-embed-text

# Check prerequisites
npx @nano-step/nano-brain@latest doctor

# Start server
npx @nano-step/nano-brain@latest

Also available as: npx nano-brain@latest (unscoped alias)

Note: Do NOT run npx nano-brain from the nano-brain source directory — npm will resolve the local package instead of the registry. Run from any other directory.

Option D: Build from source

# Build
CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain

# Start PostgreSQL + pgvector (example with Docker)
docker run -d --name nanobrain-pg -p 5432:5432 \
  -e POSTGRES_USER=nanobrain -e POSTGRES_PASSWORD=nanobrain -e POSTGRES_DB=nanobrain_dev \
  pgvector/pgvector:pg17

# Start server
DATABASE_URL="postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev" ./nano-brain

# Register workspace
curl -X POST http://localhost:3100/api/v1/init \
  -H "Content-Type: application/json" \
  -d '{"root_path":"/path/to/project","name":"my-project"}'

# Write a document
curl -X POST http://localhost:3100/api/v1/write \
  -H "Content-Type: application/json" \
  -d '{"workspace":"<hash>","source_path":"notes/decision.md","content":"# Decision\nUse PostgreSQL.","tags":["decision"]}'

# Search
curl -X POST http://localhost:3100/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"workspace":"<hash>","query":"database decision"}'

Verifying Downloads

Every release ships a SHA256SUMS asset alongside the four platform binaries.
You can verify a downloaded binary against the published checksums using
standard tooling:

TAG=v2026.6.2.1   # any release tag
curl -fLO https://github.com/nano-step/nano-brain/releases/download/$TAG/SHA256SUMS
curl -fLO https://github.com/nano-step/nano-brain/releases/download/$TAG/nano-brain-linux-amd64
sha256sum -c SHA256SUMS --ignore-missing
# nano-brain-linux-amd64: OK

npm install @nano-step/nano-brain (and the unscoped nano-brain alias)
performs this verification automatically during postinstall — a SHA-256
mismatch aborts the install with exit code 1 and removes the partial binary.

For air-gapped installs or environments where a corporate proxy modifies the
download stream, set NANO_BRAIN_SKIP_SHA_VERIFY=1 before running npm install
to bypass the check (a warning is printed so the bypass is visible in CI logs).

Releases tagged before this feature shipped do not have a SHA256SUMS asset;
installs of those versions succeed with a single WARN line and no verification.
See issue #320 for the
threat model and rationale.

Configuration

Config file: ~/.nano-brain/config.yml

server:
  host: localhost
  port: 3100

database:
  url: postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev

embedding:
  provider: ollama              # ollama or voyage
  url: http://localhost:11434
  model: nomic-embed-text
  dimension: 0                  # auto-detect from provider
  concurrency: 3

search:
  rrf_k: 60
  recency_weight: 0.3
  recency_half_life_days: 180
  limit: 20

harvester:
  opencode:
    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: ""

watcher:
  debounce_ms: 2000
  reindex_interval: 300
  # Per-collection exclude_patterns and allowed_extensions are also supported
  # via the workspaces map. See "Ignore patterns" section below for the
  # global and workspace-local .nano-brainignore files.

storage:
  max_file_size: 314572800      # 300MB
  max_size: 10737418240         # 10GB

telemetry:
  retention_days: 90

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

Authentication (VPS / remote deployment)

When binding to a non-loopback address, enable auth to protect your memory:

server:
  host: 0.0.0.0
  port: 3100
  auth:
    enabled: true
    realm: nano-brain
    users:
      - username: admin
        password_hash: "$2a$10$..."   # from: nano-brain auth hash <password>
    tokens:
      - "nbt_..."                     # from: nano-brain auth token
    bypass_paths:
      - /health

Generate credentials:

# Generate bcrypt hash for Basic Auth
nano-brain auth hash mypassword

# Generate bearer token
nano-brain auth token

Usage examples:

# Basic Auth
curl -u admin:mypassword http://host:3100/api/v1/query -d '{"query":"test"}'

# Bearer token
curl -H "Authorization: Bearer nbt_..." http://host:3100/api/v1/query -d '{"query":"test"}'

# MCP client with URL-embedded credentials
# url: http://admin:mypassword@host:3100/mcp

Ignore patterns

Two layers of .nano-brainignore files control what the watcher indexes,
both using standard .gitignore syntax (one pattern per line, supports **,
!negation, blank lines, # comments).

Global — ~/.nano-brain/.nano-brainignore

Loaded once at server startup. Patterns apply to every registered
collection across every workspace. Use this for rules that are personal
to your machine and span all your projects (e.g. always skip *.png).

# Skip generated files everywhere
*.png
*.jpg
*.pdf
build/
dist/
node_modules/

# But keep this one icon
!icons/important.png

Workspace-local — <workspace_root>/.nano-brainignore

Loaded once per collection when the watcher starts watching it (server
startup, POST /api/v1/init, or POST /api/v1/collections). Patterns
apply only to that one workspace. Use this for project-specific rules
you want to share with your team via version control — e.g. skip
generated code that you commit to git but don't want indexed.

# nano-brain-specific rules for this repo (commit me)
*.generated.go
fixtures/large/
*.snap

Workspace-local rules layer additively on top of global rules and
per-collection .gitignore. There is no cross-file negation: a !pattern
in workspace-local cannot un-exclude a path matched by global.

The file at the workspace root is loaded for the code collection. The
sibling memory and sessions collections are rooted under ~/.nano-brain/
and do not normally need their own ignore files.

Order of evaluation (most aggressive first)

1. Hardcoded default exclude dirs (node_modules, .git, dist, build, target, etc.)
2. Global ~/.nano-brain/.nano-brainignore
3. Workspace-local <workspace_root>/.nano-brainignore
4. Per-collection .gitignore (in collection root)
5. Per-collection exclude_patterns (config-level)
6. Per-collection allowed_extensions (whitelist)

Reloading

Both global and workspace-local files are loaded at collection registration
time. To pick up edits:

• Global: restart the server.
• Workspace-local: restart the server, OR re-register the workspace
  with POST /api/v1/init (this rebuilds the collection's filter and
  re-reads the file).

POST /api/reload-config does not re-read ignore files — only search
config and log level are reloaded by that endpoint.

Issues: #263 (global), #317 (workspace-local).

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)
• Optionally written to disk as Markdown files for Obsidian-compatible access (see Disk persistence below)
• Idempotent — unchanged sessions are skipped; re-harvested sessions overwrite old summaries

Disk persistence (Obsidian-compatible)

By default, summaries are written to disk as Markdown files at the path configured in
summarization.output_dir (default: ~/.nano-brain/summaries). The file layout is:

<output_dir>/<workspace_name>/<source>_<slugified-title>_<YYYY-MM-DD>.md

Files are byte-identical to the documents.content field in PostgreSQL — disk is a
derivative view, DB is source of truth. Disk write failures (permission denied, disk
full) log a WARN but do not roll back the DB transaction.

To opt out (DB-only persistence):

summarization:
  write_to_disk: false

To backfill historical summaries already in the DB:

nano-brain backfill-summaries

Quick setup with ai-proxy:

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:

export NANO_BRAIN_SUMMARIZE_API_KEY="sk-..."

Large sessions (100K+ tokens) are handled via map-reduce chunking — no session is too large.

Environment Variables

Docker example — run the server in a container against a host PostgreSQL:

# /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

Public Endpoints

Workspace-Scoped Endpoints

Workspace is passed in the JSON body for POST, query param for GET.

MCP Endpoints

CLI Commands

MCP Tools

nano-brain exposes 14 tools via MCP (Model Context Protocol):

MCP Configuration

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

Search Pipeline

Query --> BM25 (ts_rank_cd) ---+
                               +--> RRF Fusion (k=60) --> Recency Decay --> Results
Query --> Vector (HNSW cos) ---+

• BM25: websearch_to_tsquery + ts_rank_cd on PostgreSQL tsvector
• Vector: pgvector HNSW index with cosine distance
• RRF: Reciprocal Rank Fusion (k=60), scores normalized to [0,1]
• Recency: exponential half-life decay (default 180 days, weight 0.3)

Architecture

• 15 internal packages: config, server, handlers, storage, sqlc, embed, search, watcher, harvest, mcp, migrate, telemetry, health, bench
• 7 goose SQL migrations (embedded)
• Constructor injection (no DI framework)
• errgroup + context for goroutine lifecycle
• Echo v4 middleware: workspace extraction, content-type enforcement, version header

Migration from V1

# Import V1 SQLite data to PostgreSQL
nano-brain db:migrate --from-v1 /path/to/old/index.db

# Idempotent — safe to run multiple times
# Uses content-addressed SHA-256 hashing
# Pure Go SQLite reader (modernc.org/sqlite, no CGO)

Tech Stack

• Go 1.23 — compiled to single static binary (CGO_ENABLED=0)
• PostgreSQL 17 — relational storage + full-text search (tsvector/tsquery)
• pgvector 0.8.2 — HNSW vector indexing
• Echo v4 — HTTP framework
• sqlc — type-safe SQL code generation
• goose v3 — database migrations
• zerolog — structured JSON logging
• koanf — YAML + env configuration
• fsnotify — file system watching
• modernc.org/sqlite — V1 migration reader (pure Go)

License

MIT