@regolet/superbrain

Persistent AI memory with auto entity extraction, knowledge graph, session continuity, and memory compaction.

A fully local, SQLite-powered MCP server that gives any AI client persistent memory. No cloud, no API keys, no subscriptions — just your brain on your machine.

npx -y @regolet/superbrain

Why SuperBrain

Every AI session starts from zero. SuperBrain fixes that.

• Remember across sessions — decisions, bugs, architecture, preferences persist forever
• Auto-extract entities — captures technology names, IPs, ports, file paths, people, and topics from your text automatically
• Knowledge graph — connects memories through typed relationships (uses, blocks, supersedes, caused_by...)
• Session continuity — save and restore structured session summaries with goals, decisions, and open threads
• Memory compaction — consolidate similar old memories into compact summaries (originals preserved in history)
• Safety check — query your brain before dangerous actions to surface past incidents and warnings
• Provenance tracking — every memory records source, confidence, evidence, importance, and staleness
• Exponential decay scoring — frequently accessed memories stay relevant, stale ones fade naturally

Quick Start

Add to your MCP client configuration:

{
  "mcpServers": {
    "superbrain": {
      "command": "npx",
      "args": ["-y", "@regolet/superbrain"]
    }
  }
}

Your database is created automatically at ~/.superbrain/brain.db.

Tools (22)

Core Memory

| Tool | Description | |------|-------------| | search | Hybrid search with FTS5, vector similarity, project-aware relevance scoring | | recent_thoughts | Browse recent memories with type, topic, project, source, and tier filters | | thought_stats | Overview of your brain — totals, projects, sources, stale count, top topics | | capture_thought | Save a memory with auto entity extraction, evidence, provenance, and staleness | | summarize_topic | Extractive briefing from matching memories with key thoughts and action items | | find_duplicate_thoughts | Detect near-duplicate memories using Jaccard similarity | | related_thoughts | Expand from one memory to related ones by topic, entity, person, and project | | project_profile | Summarize a project's memory profile — tiers, entities, important memories | | backfill_embeddings | Generate missing local vector embeddings for older memories | | merge_thoughts | Merge duplicate memories into a primary, preserving metadata | | export_thoughts | Export as JSON or Markdown | | import_thoughts | Import from a JSON export with dry-run validation |

Session Continuity

| Tool | Description | |------|-------------| | capture_session | Save a structured session summary with goals, decisions, and open threads | | get_last_session | Restore context from the most recent session for a project |

Memory Lifecycle

| Tool | Description | |------|-------------| | thought_history | View how a memory evolved over time (updates, merges, compaction) | | archive_stale | Move stale/expired memories to archive with dry-run preview | | search_archive | Search through archived memories for old context | | compact_memories | Consolidate similar old memories into summaries (originals preserved) |

Knowledge Graph

| Tool | Description | |------|-------------| | link_thoughts | Create typed relationships: uses, blocks, supersedes, caused_by, related_to, depends_on, contradicts, confirms | | thought_links | View all connections from and to a memory with direction filtering |

Safety

| Tool | Description | |------|-------------| | check_before_action | Search for warnings, incidents, or blockers before performing dangerous operations |

Auto Entity Extraction

SuperBrain automatically extracts structured data from your plain text:

Input:  "LiteFi uses Redis on Contabo server 192.168.1.100 port 6379, deployed by @regolet via PM2"

→ Entities: [LiteFi, Redis, Contabo, PM2, port 6379, 192.168.1.100]
→ People:   [regolet]
→ Links:    6 knowledge graph connections auto-created

Recognized patterns:

• Technology names — Redis, PostgreSQL, Docker, React, Next.js, PM2, Nginx, and 40+ more
• PascalCase identifiers — LiteFi, SuperBrain, FastAPI (code/project names)
• Infrastructure — IP addresses, port numbers, file paths
• People — @mentions, "Name said/confirmed/decided" patterns
• Topics — #hashtag patterns

Evidence-Based Capture

Every memory can carry provenance evidence:

capture_thought(
  content: "PM2 restart command: pm2 restart litefi-api",
  evidence: "Confirmed working during 2026-05-15 deployment",
  evidence_source: "deployment"
)

Evidence-backed memories receive an importance boost and form a verifiable audit trail.

Memory Lifecycle

┌─────────────┐     ┌──────────────┐     ┌────────────────┐
│   capture    │ ──▸ │   active     │ ──▸ │   stale        │
│  (extract +  │     │  (search +   │     │  (warned but   │
│   auto-link) │     │   access)    │     │   accessible)  │
└─────────────┘     └──────────────┘     └────────────────┘
                          │                      │
                          ▼                      ▼
                    ┌──────────────┐     ┌────────────────┐
                    │  compacted   │     │   archived     │
                    │  (merged     │     │  (preserved    │
                    │   summary)   │     │   offline)     │
                    └──────────────┘     └────────────────┘

• Auto staleness — operational memories auto-calculate stale dates by type
• Exponential decay — relevance score uses e^(-age/90) with access-count rescue
• Compaction — groups similar old memories and merges them into summaries
• Archival — moves expired memories to a searchable archive
• History — every update, merge, and compaction is logged with full content

Session Hooks

Auto-capture session summaries when your AI client disconnects:

npx -p @regolet/superbrain superbrain-install-hooks

This installs a stop-hook that extracts session intent, outcome, and topics from the transcript and saves it to SuperBrain automatically.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | SUPERBRAIN_DIR | ~/.superbrain | Database directory | | SUPERBRAIN_PROJECT | — | Default project for new captures and search boost | | SUPERBRAIN_EMBEDDINGS | 1 | Set to 0 to disable local vector embeddings | | SUPERBRAIN_EMBEDDING_MODEL | Xenova/all-MiniLM-L6-v2 | Local embedding model | | SUPERBRAIN_EMBEDDINGS_QUIET | — | Set to 1 to suppress embedding fallback warnings |

CLI

# Start the MCP server
npx @regolet/superbrain

# Show database info
npx @regolet/superbrain --info

# Backfill embeddings for older memories
npx -p @regolet/superbrain superbrain-backfill --limit=100

# Install session auto-capture hooks
npx -p @regolet/superbrain superbrain-install-hooks

Architecture

~/.superbrain/brain.db
├── thoughts          — Active memories with FTS5 index + vector embeddings
├── thought_history   — Version log of all changes (update, merge, compact)
├── thought_links     — Knowledge graph: typed entity relationships
├── archived_thoughts — Preserved stale/expired memories
└── sessions          — Structured session summaries

4 source files. 4 dependencies. Zero cloud.

| File | Purpose | Size | |------|---------|------| | database.js | Schema, queries, scoring, extraction, compaction | ~57 KB | | tools.js | 22 MCP tool registrations with Zod schemas | ~36 KB | | embeddings.js | Local vector embeddings via Transformers.js | ~1.5 KB | | index.js | MCP server entry point | ~2 KB |

Scoring Algorithm

Search relevance combines multiple signals:

score = lexical_match          (token overlap + phrase match)
      + fts5_boost             (FTS5 rank when available)
      + vector_similarity      (cosine distance when embeddings exist)
      + project_boost          (configurable: boost vs only vs all)
      + confidence_weight      (source reliability)
      + importance_weight      (manual or inferred)
      + tier_bonus             (procedural memories prioritized)
      + exponential_decay      (e^(-age/90) × 1.5)
      + access_rescue          (log₁(access_count) × 0.3)

License

FSL-1.1-MIT. Forked from Open Brain (OB1).