Brain Memory

A hierarchical, file-system-based memory system for AI coding agents. Inspired by human neuroscience — memories decay, strengthen through recall, and connect via associative networks.

Brain Memory works with Claude Code, OpenAI Codex CLI, OpenCode, GitHub Copilot CLI, Kilo, and Google Antigravity — with the Claude.ai and ChatGPT apps through a hosted MCP connector, and with OpenClaw and Hermes Agent through native integrations.

What is Brain Memory?

Brain Memory gives your AI coding agent persistent, long-term memory that behaves like the human brain. Instead of a flat database or vector store, memories are organized into a deep nested directory tree that encodes semantic meaning through its hierarchy:

~/.brain/
├── professional/
│   └── companies/
│       └── acme-corp/
│           └── projects/
│               └── alpha-launch.md        ⚡ 0.88
├── personal/
│   └── education/
│       └── typescript-generics.md         ⚡ 0.72
├── social/
│   └── communities/
│       └── open-source-contrib.md         ⚡ 0.65
└── family/
    └── events/
        └── annual-reunion-planning.md     ⚡ 0.55

Every memory is a Markdown file with YAML frontmatter. Human-readable, Git-friendly, and completely portable.

Why Brain Memory?

Existing AI memory solutions use flat databases with tag-based retrieval. Brain Memory is different:

• The directory tree IS the semantic structure — professional/companies/acme/projects/ tells the agent everything about context without vector search
• Human-inspectable — Browse your "brain" in any file explorer
• Git-friendly — Full version history of how memories evolve
• Strength + decay — Recalled memories get stronger, forgotten ones fade. Just like your brain
• Associative network — Memories link to each other with weighted connections. Recalling one activates related ones automatically
• Context-dependent recall — Memories encoded in a similar context to the current session are scored higher
• Spaced reinforcement — Memories recalled after longer intervals get bigger boosts; cramming produces diminishing returns
• Cognitive types — Episodic, semantic, and procedural memories each decay differently, just like in the brain
• Consolidation — Weak related memories merge into stronger combined knowledge
• Zero dependencies — Pure file I/O, no databases, no servers, no embeddings required

Key Features

Neuroscience-Inspired Memory Model

Brain Memory implements mechanisms from peer-reviewed neuroscience research:

Memory Lifecycle

Create → Store → Decay → Recall → Reinforce → Review → Sleep → Archive
                                      ↑                   │
                                      └── Associations ────┘

1. Create — /brain:memorize analyzes the session and extracts significant decisions, learnings, insights, or experiences
2. Store — Each memory is filed into the hierarchy at the appropriate depth with full metadata
3. Decay — Memories naturally weaken over time via exponential decay
4. Recall — /brain:remember searches, scores with spreading activation and context matching, and returns the best matches
5. Reinforce — Each recall applies spaced reinforcement and improves decay resistance
6. Review — SM-2 spaced repetition reinforces due memories automatically during the sleep cycle
7. Sleep — /brain:sleep performs a 9-phase maintenance cycle inspired by real neuroscience
8. Archive — Fully decayed memories move to _archived/ where they remain recoverable and searchable

Session Lifecycle

Brain Memory works automatically in the background. When a session begins, the agent loads relevant memories silently and references them naturally. When a session ends, it suggests capturing notable decisions or learnings — but never auto-memorizes without your consent.

Getting Started

Ready to give your AI agent a brain? Head to Installation to set up Brain Memory, then follow the Quick Start guide.

Commands at a Glance

The everyday loop — remember and memorize — runs automatically; you rarely type a command.