How It Works

Not RAG. Not a Journal.

ShellBrain is long-term memory for AI that grows from actual session work—and a retrieval system designed to surface the right context at the right times.

Constructive

Each Layer Grounds the Next.

session transcript
  -> episodes      # what happened
    -> memories    # what was learned
      -> concepts  # how it's organized
        -> recall  # what's retrieved

Everything grounded. Concepts point to memories. Memories point to episode events. Episode events are the raw transcript.

Evidence First

Justified.

Every durable write requires evidence: a direct reference to the specific episode event that justifies it. Not a summary. Not an inference. A foreign key to the exact moment in the session transcript.

ShellBrain would rather have no memory than a memory it cannot justify.

If the evidence is ambiguous, the write is skipped.

What Gets Stored

Current Truth.

Problems, Solutions, Failed Tactics

The unit of storage is a case: a problem, its solutions, and its failed tactics. Solutions and failed tactics are foreign-keyed to their problem. They cannot exist without it.

Facts, Preferences, Changes

Nothing is silently overwritten. When a fact changes, ShellBrain writes the new fact, records the change that caused it, and links all three.

old fact->change->new fact

Concepts

A sparse orientation graph above the concrete layer. Concepts make no factual claims themselves. They are containers with relations and links down to memories.

Episodes

The raw transcript trail: prompts, tool calls, outputs, in order. Everything else is distilled from this.

active maybe_stale stale superseded wrong archived

How Retrieval Works

Three Stages.

Seed

Two independent search lanes run in parallel: keyword BM25 for exact terms, and semantic embeddings for conceptual neighbors. Reciprocal rank fusion merges both ranked lists.

Expand

Each candidate grows outward through explicit authored edges and bounded semantic neighbor hops. Multi-hop traversal surfaces memories no query term would reach directly.

Score and Pack

The pipeline fills each section to its quota, deduplicates globally, and returns a bounded context pack. Every item says why it was included.

The ShellBrain Subconscious

Inner Agents.

Your coding agent calls recall when it needs context, gets an answer, and moves on. What produced that answer is not its concern.

Inner agents handle the rest: one distills sessions into memories, and one answers recall by searching, weighing what is current, and returning a brief.

One lever, pulled once. Everything that makes it feel like instinct runs out of sight.

Local Only

Ownership.

Nothing leaves the machine. No telemetry. No cloud retrieval. The embedding model runs locally.

The database is Postgres + pgvector, either managed locally via Docker or on your own infrastructure. Your knowledge graph is yours.