Skip to main content
Glama
reflex-brain

reflex-brain

by dokiromboide

Reflex Brain

Continual learning brain for AI agents — lessons, skills, and memories with evidence-based refinement, rollback, and GraphRAG retrieval.

License: MIT Python Status

Overview

Reflex Brain is an agent-agnostic, continual learning memory system that gives AI agents the ability to:

  • Learn continuously from interactions — extract lessons, skills, and memories with evidence

  • Refine knowledge through evidence-based updates (/refine equivalent) with full audit trail

  • Rollback safely — snapshot-based versioning with one-click revert

  • Retrieve intelligently — GraphRAG + continual memory hybrid queries with quality filtering

  • Run anywhere — MCP server for Hermes/Claude Code/Codex, or as standalone library

Related MCP server: Consciousness MCP Server

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      AGENT LAYER                            │
│  Hermes │ Claude Code │ Codex │ OpenInterpreter │ Custom   │
└────────────────────────────┬────────────────────────────────┘
                             │ MCP / Python API
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    REFLEX BRAIN CORE                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  Lessons    │  │  Skills     │  │  Memories   │          │
│  │  (versioned)│  │  (executable)│  │  (episodic) │          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
│         │                │                │                  │
│         └────────────────┼────────────────┘                  │
│                          ▼                                   │
│              ┌──────────────────────┐                        │
│              │  Refinement Engine   │  ← Evidence-based      │
│              │  (propose/validate/  │     updates + rollback │
│              │   apply/rollback)    │                        │
│              └──────────┬───────────┘                        │
│                         │                                    │
│              ┌──────────▼───────────┐                        │
│              │  Snapshot Store      │                        │
│              │  (full checkpoints)  │                        │
│              └──────────────────────┘                        │
└─────────────────────────────────────────────────────────────┘

Key Features

Feature

Description

Lessons

Versioned knowledge units with evidence, confidence scores, and semantic clusters

Skills

Executable capabilities (Python/JS) with interfaces, tests, and versioning

Memories

Episodic memories with importance decay and temporal context

Refinement Engine

Proposes, validates, and applies updates based on evidence weight

Snapshots

Full state checkpoints for safe rollback

Hybrid Querier

Combines GraphRAG (conversations) + Continual (lessons/skills/memories)

Quality Filtering

Penalizes tool outputs, boosts substantial content, prioritizes high-value types

MCP Server

Thin wrapper exposing reflex_* tools over stdio

Daemon

Background processor for passive capture + continuous embedding

Installation

# From PyPI (when published)
pip install reflex-brain

# From source
git clone https://github.com/jesuscaicedo800/reflex-brain.git
cd reflex-brain
pip install -e ".[dev]"

Quickstart

As MCP Server (Hermes, Claude Code, Codex)

# config.yaml
mcp_servers:
  reflex-brain:
    command: "python"
    args: ["-m", "continual_brain.mcp.server"]
    env:
      HF_HUB_OFFLINE: "1"
      REFLEX_DB_PATH: "~/reflex-brain/continual.db"
      REFLEX_FAISS_PATH: "~/reflex-brain/"

Restart your agent — tools available: reflex_query, reflex_propose_lesson, reflex_apply_refinement, reflex_rollback, reflex_snapshot.

As Python Library

from continual_brain import ReflexBrain

brain = ReflexBrain(db_path="continual.db")

# Query (GraphRAG + Continual hybrid)
results = brain.query("DIAN facturación electrónica", top_k=5)

# Propose a lesson from recent session
proposal = brain.propose_lesson("DIAN compliance", session_id="sess_123")

# Apply with evidence threshold
brain.apply_refinement(proposal, auto_apply=True)

# Rollback if needed
brain.rollback(refinement_id="ref_abc")

Run Daemon (Background Processing)

# Foreground
reflex-brain daemon --poll-interval 3 --batch-size 50

# Background service
reflex-brain daemon --daemonize

Configuration

Env Var

Default

Description

REFLEX_DB_PATH

./continual.db

SQLite database path

REFLEX_FAISS_PATH

./

FAISS index directory

HF_HUB_OFFLINE

0

Set 1 to disable HF Hub requests

REFLEX_EMBED_MODEL

all-MiniLM-L6-v2

Sentence transformer model

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .

# Type check
mypy continual_brain

# Pre-commit
pre-commit install

Project Structure

reflex-brain/
├── continual_brain/
│   ├── core/           # Models, Store, RefinementEngine, Evidence
│   ├── query/          # BrainQuerier, ContinualQuerier, HybridQuerier
│   ├── daemon/         # Processor, Extractor, Embedder
│   ├── mcp/            # Thin MCP server wrapper
│   └── cli/            # CLI entry points
├── tests/
│   ├── unit/           # Unit tests
│   └── integration/    # Integration tests
└── pyproject.toml

License

MIT © Jesus Caicedo

Available Tools

22 tools
reflex_apply_refinementA

Apply a stored proposal once. Explicit approval requires approved=true; auto_apply only accepts evidence above threshold.

Inputs: refinement_id (required), approved, auto_apply.

reflex_get_lessonC

Get a specific lesson by ID

Inputs: lesson_id (required).

reflex_get_refinementC

Inspect a refinement audit record.

Inputs: refinement_id (required).

reflex_get_skillC

Get a specific skill by ID

Inputs: skill_id (required).

reflex_list_lessonsC

List lessons with optional filters

Inputs: limit, status, cluster_id.

reflex_list_proposalsC

List persisted proposals and their application state.

Inputs: limit.

reflex_list_skillsC

List skills with optional filters

Inputs: limit, status.

reflex_propose_lessonC

Propose a new lesson or update from session analysis

Inputs: topic (required), tags, content, confidence, +2 more.

reflex_queryC

Query hybrid memory (GraphRAG conversations + Continual lessons/skills/memories)

Inputs: query (required), top_k, expand_depth, source_types, +2 more.

reflex_rememberB

Persist an explicitly supplied episodic memory; returns its stable ID.

Inputs: content (required), tags, context, importance.

reflex_researchB

Automated web research: search, extract, synthesize and store knowledge on a topic

Inputs: topic (required), max_sources, create_lessons, create_memories.

reflex_rollbackC

Rollback a refinement using its snapshot

Inputs: refinement_id (required).

reflex_scheduler_add_taskC

Add a scheduled research task

Inputs: name (required), topic (required), enabled, frequency, +4 more.

reflex_scheduler_add_triggerC

Add a low-coverage trigger for automatic research

Inputs: name (required), topic_pattern (required), enabled, cooldown_hours, +2 more.

reflex_scheduler_check_coverageC

Check knowledge coverage for a topic

Inputs: topic (required).

reflex_scheduler_list_tasksC

List scheduled research tasks

Inputs: enabled_only.

reflex_scheduler_list_triggersB

List research triggers and their IDs.

Inputs: no named parameters.

reflex_scheduler_remove_taskC

Remove a scheduled research task

Inputs: task_id (required).

reflex_scheduler_remove_triggerC

Remove a research trigger by ID.

Inputs: trigger_id (required).

reflex_scheduler_statsC

Get scheduler statistics

Inputs: no named parameters.

reflex_snapshotC

Create a manual snapshot of current state

Inputs: label (required).

reflex_statusA

Inspect version, memory counts, indexing and scheduler state without loading an embedding model.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools target a distinct resource+action (remember vs query vs research vs propose_lesson), and the scheduler_* family is clearly scoped. Minor overlap exists between reflex_query and list_lessons/list_skills, and between scheduler_check_coverage and reflex_status, since both report knowledge/state summaries.

    Naming Consistency4/5

    All tools share a reflex_ prefix and snake_case, with a clean reflex_scheduler_* sub-namespace. Deviations are mild: several tools are verb-only or noun-only (reflex_status, reflex_snapshot, reflex_research) rather than verb_noun, but the pattern remains readable.

    Tool Count3/5

    22 tools for a memory/refinement/research brain is at the heavy end; the scheduler alone consumes 8 slots (tasks + triggers + coverage + stats) that could be consolidated. Several pairs (get_lesson/get_skill, list_lessons/list_skills) suggest mergeable surface.

    Completeness3/5

    Lifecycle coverage is strong for proposals/refinements (propose, list, get, apply, rollback) and the scheduler (add/remove/list for tasks and triggers), plus retrieval via query/research. However, there is no forget/delete for memories, no update/delete for lessons or skills, leaving dead ends for correcting or pruning stored knowledge.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers