nobrainr

Your AI agents forget everything between sessions. nobrainr fixes that.

Every time you start a new Claude Code session, your agent starts from zero. It doesn't remember what it debugged yesterday, what architecture decisions were made last week, or what patterns it discovered across your projects. You lose hours re-explaining context.

nobrainr is a self-hosted memory service that gives your AI agents persistent, searchable memory across sessions, machines, and projects. Agents store what they learn. Next session — on any machine — they recall it instantly.

What it actually does

• Agent fixes a tricky Docker networking issue on your laptop? That knowledge is available on your server too.
• Agent discovers a project convention? Every future session starts with that context.
• Import your ChatGPT history? All 2000 conversations become searchable agent memory.
• A knowledge graph builds itself in the background — entities, relationships, and insights extracted automatically.

# Agent stores a learning
memory_store(content="pg_dump ignores --schema when used with --table",
             tags=["postgresql", "backup"], category="gotchas")

# Any agent, any machine, any session — finds it instantly
memory_search(query="postgres backup gotcha")

Architecture

graph TB
    subgraph Agents
        A1[Claude Code<br/>Machine A]
        A2[Claude Code<br/>Machine B]
        A3[Cursor / Windsurf<br/>Machine C]
    end

    A1 & A2 & A3 -->|MCP over HTTPS| NB

    subgraph nobrainr [nobrainr server :8420]
        NB[FastMCP + JSON API]
        NB --> EMB[Ollama<br/>nomic-embed-text]
        NB --> EXT[Ollama<br/>qwen3.5:9b<br/>Entity Extraction]
        NB --> PG[(PostgreSQL 18<br/>+ pgvector)]
    end

    subgraph Storage [Knowledge]
        PG --> MEM[Memories<br/>vector similarity]
        PG --> KG[Knowledge Graph<br/>entities + relations]
        PG --> EVT[Events + Feedback]
    end

    NB --> DASH[Vue 3 Dashboard<br/>Graph · Memories · Timeline]

    style nobrainr fill:#1a1a2e,stroke:#16213e,color:#e6e6e6
    style Agents fill:#0d1117,stroke:#30363d,color:#e6e6e6
    style Storage fill:#0d1117,stroke:#30363d,color:#e6e6e6

<p align="center"> <img src="docs/nobrainr-architecture.png" alt="nobrainr Knowledge Flywheel Architecture" width="800"> </p>

Fully local. No API keys. No cloud. Your data stays on your hardware. Built on PostgreSQL + pgvector for storage, Ollama for free local embeddings, and MCP as the standard interface.

Quick start

Docker (recommended)

git clone https://github.com/youruser/nobrainr.git
cd nobrainr
cp .env.example .env

# Edit .env — at minimum, set a real POSTGRES_PASSWORD
$EDITOR .env

# Start everything
docker compose up -d

# Wait for llama-swap to load the model stack (one-time on first start)
docker compose logs -f llama-swap

# Verify
curl -sf http://localhost:8420/api/stats | jq .total_memories

The reference deployment runs llama-swap with three on-GPU llama-server processes: Qwen3.6-27B-IQ4_XS (main LLM, port 5803, 32K ctx), Qwen3-Embedding-0.6B (embeddings, port 5802, 1024-dim), and bge-reranker-v2-m3 (reranker, port 5800). Fits in ~18 GB VRAM. See Deployment for alternative single-GPU stacks and CPU-only fallbacks. If you don't need automatic entity extraction (knowledge graph), set NOBRAINR_EXTRACTION_ENABLED=false in .env to skip it.

Local development

# Start only the infrastructure
docker compose up -d postgres llama-swap

# Run the backend locally
uv sync
uv run nobrainr serve

# Or run the dashboard too
cd dashboard && npm install && npm run dev

Connect your AI client

Replace <your-server> with your nobrainr host IP or domain. For remote access, use a reverse proxy with TLS (see Deployment — Security).

<details> <summary><b>Claude Code</b></summary>

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "nobrainr": {
      "type": "http",
      "url": "https://<your-domain>/mcp"
    }
  }
}

For local-only access (same machine):

{
  "mcpServers": {
    "nobrainr": {
      "url": "http://localhost:8420/mcp"
    }
  }
}

Or follow the Claude Code setup guide for full integration with hooks and scripts. </details>

<details> <summary><b>Claude Desktop</b></summary>

Add to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "nobrainr": {
      "type": "http",
      "url": "https://<your-domain>/mcp"
    }
  }
}

</details>

<details> <summary><b>Cursor</b></summary>

Settings > MCP > Add Server:

• Type: HTTP
• URL: https://<your-domain>/mcp </details>

<details> <summary><b>Windsurf / Cline / any MCP client</b></summary>

HTTP (recommended):

{
  "mcpServers": {
    "nobrainr": {
      "type": "http",
      "url": "https://<your-domain>/mcp"
    }
  }
}

SSE (legacy, still supported):

{
  "mcpServers": {
    "nobrainr": {
      "type": "sse",
      "url": "https://<your-domain>/sse"
    }
  }
}

</details>

Security note: Never expose nobrainr directly to the internet without TLS and access control. Use a reverse proxy with HTTPS, and restrict access via VPN, IP allowlist, or authentication.

MCP Tools

Tool	What it does
memory_store	Save a memory (auto-embeds, dedup check, async entity extraction)
memory_search	Semantic search with natural language (relevance-ranked)
memory_query	Filter by tags, category, machine, source
memory_get	Get one memory by ID
memory_update	Update a memory (re-embeds if content changes)
memory_delete	Delete a memory by ID
memory_stats	Counts by category, machine, source, top tags + knowledge graph stats
entity_search	Semantic search on knowledge graph entities
entity_graph	Recursive graph traversal from a named entity
memory_maintenance	Recompute importance scores + decay stability
memory_extract	Manually trigger entity extraction for a memory
memory_feedback	Report whether search results were helpful (improves ranking)
memory_reflect	Batch-save learnings from a session
log_event	Record agent activity (session starts, decisions, completions)
memory_import_chatgpt	Import from ChatGPT export
memory_import_claude	Import from .claude/ directory

Example calls

# Store
memory_store(content="Traefik needs container DNS names, not IPs",
             tags=["traefik", "docker"], category="gotchas",
             source_machine="my-server")

# Search
memory_search(query="how did we fix the Docker networking issue")

# Filter
memory_query(source_machine="my-laptop", category="architecture", limit=20)

Autonomous Learning

nobrainr runs background scheduler jobs that continuously improve the knowledge base:

Job	Interval	What it does
Maintenance	6h	Recompute importance scores, decay stale memories
Summarize	1h	Auto-summarize memories that lack summaries
Consolidation	2h	Merge near-duplicate memories (cosine > 0.88)
Synthesis	4h	Generate insights from entity clusters
Entity enrichment	2h	Improve entity descriptions
Insight extraction	1h	Extract learnings from agent events
ChatGPT distillation	6min	Distill imported ChatGPT conversations into memories
Contradiction detection	4h	Find and flag contradicting memories
Cross-machine insights	6h	Discover patterns across machines
Extraction quality	4h	Validate entity extractions, prune bad links
Memory decay	24h	Archive low-value, never-accessed old memories

All jobs are configurable via environment variables. See .env.example.

These jobs require an Ollama model with structured output support. On CPU-only servers, expect ~60-120s per LLM call — the scheduler handles this with sequential processing and cooldowns.

Hooks & Skills (optional)

The scripts/ directory contains Claude Code integrations:

Auto-load on session start — A hook queries nobrainr for relevant memories and injects them as startup context.

Auto-save on session end — A hook detects substantial code changes and stores a session summary.

/remember — Slash command that reviews the session and stores key insights.

/recall <query> — Slash command that searches memories.

See the Claude Code setup guide for full setup instructions.

Stack

Component	Version	Purpose
PostgreSQL	18	Storage (UUIDv7 native)
pgvector	HNSW index	Similarity search
Ollama	nomic-embed-text	Local embeddings (768d, free, no API costs)
Ollama	qwen3.5:9b	Entity extraction + autonomous learning (optional)
FastMCP	HTTP + SSE	MCP server
Python	3.12+	Runtime
Vue 3	Vuetify + Cytoscape.js	Dashboard (optional, separate container)

Configuration

All via environment variables with NOBRAINR_ prefix:

Variable	Default	Description
NOBRAINR_DATABASE_URL	postgresql://nobrainr:nobrainr@localhost:5432/nobrainr	PostgreSQL connection
NOBRAINR_OLLAMA_URL	http://localhost:11434	Ollama API endpoint
NOBRAINR_EMBEDDING_MODEL	nomic-embed-text	Ollama model for embeddings
NOBRAINR_HOST	0.0.0.0	Server bind address
NOBRAINR_PORT	8420	Server port
NOBRAINR_EXTRACTION_ENABLED	true	Enable entity extraction (knowledge graph)
NOBRAINR_EXTRACTION_MODEL	qwen3.5:9b	Ollama model for extraction
NOBRAINR_SOURCE_MACHINE	<hostname>	Machine name for scheduler-created memories
NOBRAINR_SCHEDULER_ENABLED	true	Enable background scheduler jobs

See .env.example for the full list including scheduler intervals.

Project layout

src/nobrainr/
├── mcp/server.py          # MCP tools (the API)
├── db/
│   ├── queries.py         # All database operations
│   ├── schema.py          # DDL (auto-creates tables on startup)
│   └── pool.py            # asyncpg connection pool
├── embeddings/ollama.py   # llama-server embedding client (name predates migration; routes to llama-swap)
├── extraction/
│   ├── extractor.py       # Entity/relationship extraction via Ollama
│   ├── pipeline.py        # Full pipeline: extract → dedup → store → link
│   ├── dedup.py           # Memory dedup (vector + LLM merge)
│   ├── llm.py             # Shared Ollama chat helper
│   └── models.py          # Pydantic models for extraction
├── dashboard/
│   ├── app.py             # ASGI app with lifespan
│   └── api.py             # JSON API endpoints
├── importers/
│   ├── chatgpt.py         # ChatGPT export parser
│   └── claude.py          # Claude memory scanner
├── scheduler.py           # APScheduler setup
├── scheduler_jobs.py      # Autonomous learning jobs
├── config.py              # Pydantic settings
└── cli.py                 # CLI: serve, status, search, import

dashboard/                  # Vue 3 frontend (optional, separate build)
├── Dockerfile
├── nginx.conf
├── src/
│   ├── views/             # Graph, Memories, Timeline, Scheduler
│   ├── composables/       # Vue composables for each view
│   └── components/        # Reusable UI components
└── ...

Deployment

Plain Docker

The included docker-compose.yml is self-contained. It runs PostgreSQL, Ollama, and the nobrainr server. Just docker compose up -d.

For the dashboard, build and run it separately:

cd dashboard
docker build -t nobrainr-dashboard .
docker run -d -p 3000:80 nobrainr-dashboard

Behind a reverse proxy (recommended for multi-machine)

For accessing nobrainr from multiple machines, put it behind a reverse proxy with TLS. Never expose port 8420 directly — MCP traffic includes memory content in plaintext.

nobrainr serves MCP (HTTP + SSE) and a JSON API on port 8420:

• Route /mcp to the backend (HTTP transport — recommended)
• Route /sse and /messages/* to the backend (SSE transport — legacy, don't buffer)
• Route /api/* to the backend
• Route everything else to the dashboard

Restrict access via VPN subnet, IP allowlist, or authentication at the proxy layer. See Deployment — Security for Traefik and nginx examples with TLS.

With Coolify

nobrainr works well with Coolify — connect your Git repo, set the environment variables, and deploy. The Dockerfile and dashboard/Dockerfile are ready to use.

Backups

The PostgreSQL volume contains all your memories. Back it up regularly:

docker exec nobrainr-db pg_dump -U nobrainr nobrainr | gzip > nobrainr-backup-$(date +%Y%m%d).sql.gz

To restore:

gunzip -c nobrainr-backup-20260306.sql.gz | docker exec -i nobrainr-db psql -U nobrainr nobrainr

CLI

nobrainr serve              # Start MCP server
nobrainr status             # Check DB + embedding model
nobrainr search "query"     # Semantic search from terminal
nobrainr import-chatgpt conversations.json
nobrainr import-claude ~/.claude --machine my-laptop

License

MIT