agents have no long-term memory. every session starts from zero. lessons vanish. mistakes repeat. knowledge never compounds.
shellbrain gives agents structured, long-term memory—typed, evidence-grounded, and retrieved the moment a problem resembles something already seen.
shellbrain is a skill. you start each session with it. the agent reads, writes, and evolves memory on its own.
works with claude code, cursor, and codex. installs as a native skill in each. memory is shared across all of them.
typed memory in a knowledge graph. scenarios, facts, preferences, associations—distinct node types with structural edges. not markdown files.
BM25 search fused with semantic embeddings. candidates expand through graph edges. bounded, scored, and every result explains why it was included.
prior problems and outcomes.
every problem, solution, and failed tactic linked as a scenario. the next time a similar problem appears, the agent knows what to try and what to skip.
case-based reasoning. problems are never stored in isolation—only as structured cases with outcomes.
facts, preferences, revision history.
facts are never overwritten. when knowledge changes, the old fact, the change, and the new fact are linked as an immutable revision chain. preferences capture how you like to work.
facts, preferences, and changes are distinct typed nodes with their own revision semantics.
evidence and grounding.
every durable memory must trace back to a real event. if the evidence is ambiguous, shellbrain skips the write entirely.
three-layer validation—schema, semantic, integrity—rejects anything that can't cite its evidence.
expansion beyond retrieval.
explicit graph edges and implicit vector similarity both expand recall outward—through linked scenarios, revision chains, and semantic neighbors.
multi-hop traversal surfaces memories the agent would never think to look for.
after retrieval, agents vote on which memories actually helped. utility is recorded per problem, not globally. the graph sharpens itself over time.
retrieve memories for a concrete problem. does not mutate state.
sync the session transcript. returns episode event IDs the agent can cite as evidence.
write one durable memory. at least one evidence reference is required.
record utility, evolve facts, add associations, or archive.
shellbrain runs locally. nothing leaves your machine. no cloud. no outbound telemetry.
every solution. every failure. every pattern. that's the most valuable thing you'll ever build. it belongs to you.