Nano脑

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

Team knowledge base (no per-member setup)

Deploy one nano-brain server for the whole team. Every developer's AI agent connects to the same PostgreSQL instance — decisions, architecture notes, code intelligence, and session learnings are instantly shared across the team. New team members get full project context from day one without any setup on their machine.

Dev A (office)   ──┐
Dev B (remote)   ──┼──► nano-brain on team server ──► shared PostgreSQL
Dev C (new hire) ──┘

Role-based access: admins get full read/write, developers get read/write scoped to their workspace, stakeholders or reviewers get read-only access.

Path 1 — Local machine (Ollama + Docker, ~5 min)

The fastest way to get started on a single machine.

Prerequisites: Docker, Ollama, Node.js 18+

```bash

1. Install nano-brain

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

2. Install and start nano-brain (with auth + public binding)

npm install -g @nano-step/nano-brain nano-brain serve -d --host=0.0.0.0

Path 3 — Build from source

```bash

Build

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

Via npx (no global install)

npx @nano-step/nano-brain@latest doctor
npx @nano-step/nano-brain@latest serve -d

Also available as npx nano-brain@latest. Do NOT run from the nano-brain source directory — npm will resolve the local package instead of the registry.

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:

```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 ```

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 ───┘

Quick Start

Let your AI agent set this up for you. See SETUP_AGENT.md — a step-by-step guide your agent can follow to install, configure, and verify nano-brain, checking for missing dependencies and asking before installing anything.

---

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

Environment Variables

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

```bash

MCP Configuration

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

REST API

Public Endpoints

Workspace-Scoped Endpoints

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

MCP Endpoints

CLI Commands

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)