Neurox

Persistent memory for AI coding agents

One Go binary • One SQLite file • Native performance

Quick Start • How It Works • 98% Recall • Docs • Leer en Espanol

Your AI coding agent forgets everything between sessions. Every conversation starts from scratch — no memory of the architecture decisions you made last week, the bug you fixed yesterday, or your preference for tabs over spaces.

Neurox gives your agent persistent, structured memory.

brew install joeldevz/tap/neurox           # macOS / Linux
neurox setup claude-code    # or: opencode, cursor, vscode, antigravity, claude-desktop

That's it. No Node.js, no Python, no Docker. One binary, one SQLite file, zero runtime dependencies.

What It Remembers

Your agent saves observations as it works — decisions, bugs, patterns, preferences — and retrieves them when relevant.

Agent: "We decided to use SQLite instead of PostgreSQL for single-file deployment"
  → Neurox saves it as type: decision, links it to schema.sql
  → Parses "instead of PostgreSQL" as a knowledge update
  → Three months later, agent asks "what database do we use?"
  → Returns the SQLite decision first, PostgreSQL as history

Nothing is hidden. Every observation is a row in SQLite. You can query it directly, export it, delete it, or inspect how it was scored.

Quick Start

Install

# Homebrew (macOS / Linux)
brew install joeldevz/tap/neurox

# Script install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/joeldevz/neurox/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/joeldevz/neurox/main/install.ps1 | iex

# Build from source (requires C compiler — CGO SQLite driver for native FTS5 performance)
CGO_ENABLED=1 go build -tags sqlite_fts5 -o neurox .

Configure your agent

neurox setup claude-code       # Claude Code
neurox setup opencode          # OpenCode
neurox setup cursor            # Cursor
neurox setup vscode            # VS Code (Copilot)
neurox setup antigravity       # Gemini CLI / Antigravity
neurox setup claude-desktop    # Claude Desktop

Run

neurox mcp     # MCP server (stdio) — for Claude Code, Cursor, OpenCode, etc.
neurox serve   # HTTP API + web dashboard on localhost:7438

The web dashboard has four tabs: Brain (stats and activity), Explorer (browse and search observations), Graph (interactive force-directed visualization), and Health (brain power score with recommendations).

Git integration

neurox install-hook   # post-commit hook — marks linked observations stale when files change

How It Works

Memory Layers

Observations move through three layers based on importance and access patterns:

 Buffer (new)          Working (validated)       Core (proven)
 ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
 │ All new saves   │───>│ Passed quality  │───>│ Accessed 5+    │
 │ Capacity: 200   │    │ gate or high    │    │ times, 7+ days │
 │ Fast decay      │    │ importance      │    │ old, durable   │
 └────────────────┘    └────────────────┘    └────────────────┘

Decay reduces accessibility (how easy to find), not value (whether it exists). A decision made six months ago stays in Core — it just becomes less prominent unless accessed. Nothing is deleted without explicit action.

Scoring

Score = (Recency × 0.3) + (Importance × 0.3) + (Relevance × 0.4)
        × Temporal multiplier (0.7x – 1.5x based on time intent)
        × Cross-signal boost (1.2x when FTS and semantic agree)

Graceful Degradation

Neurox works without any external services. Features activate based on what's available:

The base configuration — zero runtime dependencies — already delivers 98% recall.

Consolidation

A background pipeline runs every 30 minutes: decay → promote → dedup → contradict → reflect → evict. Every stage is deterministic and auditable. See docs/concepts.md for the full pipeline.

Benchmark Results

Evaluated on LongMemEval (ICLR 2025) — 500 questions across 6 categories, 48 distractor sessions per query.

FTS5 + BM25 + temporal scoring. No LLM required. Reproducible in ~2 minutes.

A self-contained Brain Benchmark (12 dimensions, 3 categories) is also included: neurox benchmark.

Surface Parity

Neurox exposes three access surfaces. The core memory operations — save, recall, context, and session — use the same shared pipeline across all three, guaranteeing identical quality, provenance, and hooks regardless of how you connect.

Concurrency model: MCP and HTTP use an async SaveQueue with background workers. CLI uses the same pipeline synchronously (the process exits after each command). The quality gates, fact extraction, and embedding hooks are identical in all cases.

MCP Tools

Full tool inputs and parameters: docs/reference.md

Documentation

Technology

• Go 1.26+ — single binary, goroutines for background consolidation
• SQLite 3 — WAL mode, FTS5 full-text search, via mattn/go-sqlite3 (CGO, native SQLite performance)
• MCP — Model Context Protocol via mark3labs/mcp-go
• Embeddings — Ollama or any OpenAI-compatible API (optional)
• LLM — Ollama or OpenAI-compatible (optional)
• IDs — ULID (monotonic, sortable) via oklog/ulid

Platform Support

Prebuilt binaries are attached to every GitHub Release. No Go, no C compiler, no dependencies — download and run.

Homebrew installs prebuilt binaries via the joeldevz/tap.

Build from source requires Go 1.26+ and a C compiler (gcc, clang, or MinGW on Windows) with CGO_ENABLED=1 -tags sqlite_fts5.

License

BSL 1.1 — You can use, modify, and distribute Neurox for any purpose except offering it as a commercial hosted service competing with the Licensor. On 2030-03-28, it converts automatically to Apache 2.0.

Same model as Sentry, CockroachDB, HashiCorp, and MariaDB.