convez.ai
MCP Server
joeldevz

neurox

joeldevz/neurox

Ver no GitHub
InicialPluginScore · de 0 a 100

Persistent memory for AI coding agents — your agent stops forgetting between sessions. One Go binary, one SQLite file.

Instalação

$npx convez-ai joeldevz/neurox

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.5.7
Issues abertas
8
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.


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.

FeatureSimple storeNeurox
Save and retrieve textYesYes
Full-text search (FTS5)MaybeBuilt-in
Understands time ("last week", "currently")NoTemporal reasoning
Knows when facts changeNoKnowledge updates — old facts become history, not noise
Links memories to source filesNoGit integration — auto-marks stale when files change
Explains why a result ranked firstNoDebug mode — full score breakdown
Tracks where memories came fromNoProvenance — which tool, session, and surface
Works without any external service—Yes — LLM and embeddings are optional enhancements

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:

AvailableFeatures enabled
Nothing (default)FTS5 search, temporal parsing, decay, promotion
+ Embeddings (Ollama or remote)Hybrid search, semantic dedup, contradiction detection
+ LLM (Ollama or remote)Quality gate, fact extraction, reflection
+ Curator LLM (remote)Deep curation with importance recalibration

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.

CategoryNRecall@10NDCG@10
knowledge-update72100.0%96.9%
single-session-user6498.4%97.0%
single-session-assistant5698.2%95.1%
temporal-reasoning12797.6%87.2%
multi-session12198.4%87.0%
single-session-preference3093.3%73.8%
Overall47098.1%90.0%

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.

CapabilityCLIMCPHTTP
save (shared pipeline, provenance, facts, embeddings)✓✓✓
recall (FTS5 + semantic + temporal intent + provenance)✓✓✓
context (proactive retrieval + reflections)✓✓✓
session_start / session_end (observation extraction)✓✓✓
update—✓✓
forget (soft-delete)—✓✓
invalidate (+ replacement)✓✓✓
status✓✓✓
git_hook—✓✓
reflect—✓✓
consolidate✓✓✓
health_check—✓✓
curate✓✓✓
backup✓✓✓
audit (full observation lifecycle)✓——
graph (interactive visualization)✓—✓
benchmark✓——
export / import✓——
reembed✓——
Web dashboard (Brain, Explorer, Graph, Health)——✓

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

ToolDescription
saveSave observation with FTS5 indexing and temporal extraction
recallSearch with hybrid scoring (FTS5 + semantic + temporal)
contextProactive context: recent + important + file-linked
updateUpdate observation by ID
forgetSoft-delete
invalidateMark incorrect, optionally create replacement with supersedes link
statusBrain stats: layers, staleness, facts, providers
session_startStart work session, return relevant context
session_endEnd session with summary
git_hookReport changed files, mark linked observations stale
reflectSynthesize insights from Working-layer observations
consolidateForce immediate consolidation cycle
health_checkBrain power score (0-100%) with recommendations
curateDeep curation with external LLM
backupSafe database backup while server is running

Full tool inputs and parameters: docs/reference.md


Documentation

TopicLink
Quickstartdocs/quickstart.md
Concepts & vocabularydocs/concepts.md — memory layers, temporal intent, decay curves, knowledge graph, provenance, debug mode, brain power score
Full referencedocs/reference.md — CLI commands, REST API, MCP tool inputs, configuration, environment variables, architecture
Claude Codedocs/claude-code.md
Claude Desktopdocs/claude-desktop.md
Cursordocs/cursor.md
VS Codedocs/vscode.md
OpenCodedocs/opencode.md

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

PlatformArchitectureBinaryHomebrewBuild from source
macOSApple Silicon (arm64)✓✓✓
macOSIntel (amd64)✓✓✓
Linuxx86_64 (amd64)✓✓✓
LinuxARM64 (arm64)✓✓✓
Windowsx86_64 (amd64)✓—✓
WindowsARM64——untested
FreeBSDany——untested

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.

Ver o original no GitHub

Bom para

Relacionados