problems, solutions, failed tactics.
procedural memory. the obstacle, what fixed it, what didn't. solutions and failed tactics must link back to their problem. without that link, the write is rejected.
for agents
long-term memory for your session.
shellbrain is a case-based memory system scoped to a repo. it stores what happened, what worked, what failed, and what the human prefers—then retrieves the relevant pieces the moment a similar problem surfaces. your job is to query it, use it, and write back what you learn.
four operations. that's it.
read
retrieve memories related to a concrete problem. re-run whenever the problem shifts.
events
sync the active session transcript. returns episode event ids to cite as evidence. run before every write.
create
write one durable memory. at least one evidence reference required.
update
evolve existing memories. utility votes, fact revisions, association links, or archive.
what to store.
facts, preferences, changes.
semantic memory. durable truths about the repo, conventions about how work should be done, and the events that invalidated prior truth. facts are never overwritten—they are revised through an immutable chain.
link memories in a knowledge graph.
association links.
you can formally link any two memories with a typed, directed edge. each edge has a relation type—depends on or associated with—plus optional confidence and salience scores between zero and one. these are durable, first-class records in the graph.
how recall uses them.
during read, shellbrain walks your explicit links up to two hops deep. linked memories surface in the explicitly related section of the context pack alongside problem-attempt and fact-revision chains. the stronger and more salient the edge, the higher it ranks.
when to link.
link memories when the relationship matters for future retrieval. a solution that depends on a specific fact. a preference that relates to an architectural decision. link at create time or add links later via update. every link requires evidence.
vote on what helped.
utility votes.
after solving a problem, vote on whether each retrieved memory actually helped. the scale is a real number from negative one to one. positive means helpful. negative means misleading. zero means neutral. votes are always scoped to a specific problem.
why it matters.
votes accumulate across sessions and agents. memories that consistently help rank higher in future retrieval. memories that consistently mislead sink. utility is earned from real feedback, not assumed.
session rhythm.
start with focused read queries about the concrete problem you are working on. not vague prompts. name the failure mode, the subsystem, the constraint.
re-run read whenever the search shifts or you hit a new subproblem. run events before every write. reuse the returned episode event ids as evidence references. never invent evidence. if it's ambiguous, skip the write.
at session end, normalize what happened into durable memories. store the problem. store each failed tactic. store the solution. store any facts, preferences, or changes that emerged. link related memories. record utility votes for memories that helped or misled.
advisory, not authoritative.
current repo state is always ground truth. shellbrain is long-term memory that answers one question: have i seen anything like this before, and what was useful? run shellbrain --help to see exact syntax for every operation.
explore.
sitemap
memory procedural → shellbrain.ai/memory/procedural semantic → shellbrain.ai/memory/semantic episodic → shellbrain.ai/memory/episodic associative → shellbrain.ai/memory/associative recall → shellbrain.ai/recall for agents → shellbrain.ai/agents for humans → shellbrain.ai/humans home → shellbrain.ai