Braingram

Persistent memory and cognitive pipeline for Claude Code.

Braingram gives Claude a brain that learns from mistakes, surfaces pain memories at the moment you're about to repeat them, and enforces workflow discipline across sessions. Not a note-taking tool. A cognitive system.

What it does

• Pain memories at decision points. Before every file edit, relevant past mistakes are injected into Claude's context. Not at session start when they're abstract -- at the exact moment of action.
• Cross-cutting change detection. When edits span 3+ architectural layers within a session, Claude gets warned before creating the kind of piecemeal changes that break apps.
• Startup gate enforcement. Claude physically cannot skip the session checklist. Hooks hard-block code edits until the conductor is scheduled.
• Signal auto-capture. Corrections, instructions, and discoveries from conversation are detected and queued for memory storage. Nothing slips through.
• Memory consolidation. Background conductor runs every 5 minutes: links related memories, extracts rules from patterns, clusters insights, grades brain health.
• Workflow discipline. Task tracking, workflow phases, two-strike error system, journal. Claude can't write code without an active task.

Install

claude plugin add braingram

Or manually: clone this repo into ~/.claude/plugins/braingram/.

How it works

On install, Braingram registers 12 hooks into Claude Code's lifecycle:

| Hook | What it does | |---|---| | SessionStart | Injects full context, initializes brain state, creates startup gate | | UserPromptSubmit | Retrieves relevant memories, status line, signal detection | | PreToolUse (Write/Edit) | Pain injection, cross-cutting detection, task/workflow gates | | PreCompact | Saves context before compression | | Stop | Captures significant moments | | SessionEnd | Auto-summarizes the session | | PostToolUse (CronCreate) | Clears startup gate when conductor is scheduled |

Plus an MCP server with 21 tools for memory, tasks, workflow, decisions, and brain health.

State directory

All state lives in .brain/ in your project root. Auto-created on first run.

.brain/
  config.json          # Project config
  memories.json        # Stored memories (pain, win, fact, skill, decision, architecture)
  brain-state.json     # Session state (message count, traces, decay)
  tasks.json           # Task tracking
  workflow.json        # Workflow phase (idle -> scope -> plan -> build -> verify -> ship)
  decisions.json       # Architecture decision log
  learned-rules.json   # Rules extracted from memory patterns
  signal-queue.json    # Auto-captured signals pending storage

MCP Tools

All tools use the bg_ prefix:

Memory: bg_store_memory, bg_retrieve_memories, bg_brain_health, bg_preview_prune, bg_restore_memory, bg_brain_export, bg_brain_import

Tasks: bg_add_task, bg_list_tasks, bg_get_task, bg_update_task, bg_start_task

Workflow: bg_advance_phase, bg_record_decision, bg_write_handoff, bg_record_failure, bg_reset_strikes, bg_end_session

Context: bg_get_context, bg_notify, bg_journal_entry

Brain engine

14 TypeScript modules implementing a biologically-inspired cognitive pipeline:

1. Tokenizer -- prompt decomposition
2. Attention filter -- keyword-triggered hard warnings
3. Pattern recognition -- keyword -> tag -> memory scoring via sensory cortex
4. Associative chaining -- matched memories pull in neighbors
5. Amygdala weighting -- severity multiplies scores
6. Synaptic strength -- historical effectiveness
7. Context awareness -- late-session reduces retrieval volume
8. Dopamine injection -- wins surfaced alongside pain
9. Session pattern detection -- hot tag warnings
10. Quality gate -- duplicate detection, conflict resolution, fingerprinting
11. Linker -- cross-memory links, contradiction detection
12. Reflection -- meta-observations, consolidation, surprise detection
13. Prediction -- expectation models, prediction errors
14. Cortex learner -- gap analysis, learning from observations

Demo

Interactive visualizer that shows the brain working in real time. Store memories, run retrieval queries, watch the quality gate accept/reject/merge entries, and inspect the link graph.

cd your-project
npx braingram-demo
# or from the repo:
node demo/serve.mjs .

Opens at http://localhost:3847. Seeds example memories so you can see the pipeline in action without a real session.

Differentiators

| Feature | Braingram | claude-mem (21K stars) | Other memory plugins | |---|---|---|---| | Quality gate on store | Dedup + conflict resolution | Record everything | Record everything | | Pain injection at edit time | PreToolUse hook | Session start only | Session start only | | Cross-cutting detection | Layer tracking + warning | No | No | | Memory consolidation | Linking + rules + clustering | No | No | | Workflow enforcement | Hard blocks via hooks | No | No | | Signal auto-capture | Regex + structural validation | No | No |

License

AGPL-3.0

Author

@Wittlesus