# Brain Memory

> A hierarchical, file-system-based memory system for AI coding agents, inspired by human neuroscience — memories decay on an Ebbinghaus curve, strengthen through recall, connect via associative networks, and consolidate during a sleep cycle. A deterministic recall engine gives identical scoring across Claude Code, Gemini CLI, OpenAI Codex CLI, and OpenCode: one brain, any model, every agent.

Brain Memory stores every memory as a human-readable Markdown file with YAML frontmatter in a single global `~/.brain/` directory — no database, no server. It is free and open source (npm package: `brain-memory`).

## Getting Started

- [Overview](https://brainmemory.ai/docs): Introduction to Brain Memory — a neuroscience-inspired memory system for AI coding agents.
- [Installation](https://brainmemory.ai/docs/getting-started/installation): Install the Brain Memory plugin for Claude Code, OpenAI Codex CLI, OpenCode, and Antigravity — or add the hosted MCP connector.
- [Quick Start](https://brainmemory.ai/docs/getting-started/quick-start): Get up and running with Brain Memory in under 5 minutes.
- [Use Brain in Claude apps](https://brainmemory.ai/docs/getting-started/claude-apps): Recall your brain from Claude on the web, desktop, and your phone via the Brain connector (remote MCP).

## Concepts

- [Memory Types](https://brainmemory.ai/docs/concepts/memory-types): Learn about the 8 memory types: decision, insight, goal, experience, learning, relationship, preference, and observation.
- [Cognitive Types](https://brainmemory.ai/docs/concepts/cognitive-types): Understand episodic, semantic, and procedural memory — modeled after human cognition.
- [Strength & Decay](https://brainmemory.ai/docs/concepts/strength-decay): How memories strengthen through recall and weaken over time via exponential decay.
- [Associative Network](https://brainmemory.ai/docs/concepts/associative-network): Memories connect via weighted edges with spreading activation and Hebbian learning.
- [Context-Dependent Recall](https://brainmemory.ai/docs/concepts/context-recall): Memories encoded in a similar context to the current session are scored higher during recall.
- [Salience & Confidence](https://brainmemory.ai/docs/concepts/salience-confidence): Emotional significance and epistemic certainty scores that influence memory behavior.
- [Provenance & Trust](https://brainmemory.ai/docs/concepts/provenance-trust): Every memory is labelled by origin, and origin bounds what it may claim — at write time and at recall.
- [Pinned Memory](https://brainmemory.ai/docs/concepts/pinned-memory): Pin critical conventions and preferences to the always-present tier — loaded every session, never decaying.
- [Procedural Skills](https://brainmemory.ai/docs/concepts/procedural-skills): Reusable how-to workflows served via progressive disclosure and learned from repeated experience.

## Commands

- [remember](https://brainmemory.ai/docs/commands/remember): Recall relevant memories using spreading activation and context-dependent scoring.
- [memorize](https://brainmemory.ai/docs/commands/memorize): Store new memories from the current session context with automatic categorization.
- [status](https://brainmemory.ai/docs/commands/status): Dashboard with brain health overview, memory counts, and strength distribution.
- [pin](https://brainmemory.ai/docs/commands/pin): Pin a memory to the always-present tier — loaded every session, never decaying. Toggles: also unpins.
- [forget](https://brainmemory.ai/docs/commands/forget): Decay or archive memories. With --deep, performs forensic erasure — traces and removes every reference.
- [import](https://brainmemory.ai/docs/commands/import): Cold-start a brain from transcripts your agents already wrote. Incremental — safe to re-run.
- [sync](https://brainmemory.ai/docs/commands/sync): Sync via Brain Cloud, Git remote, or export/import (auto-initializes the brain on first run).
- [skill](https://brainmemory.ai/docs/commands/skill): Manage procedural skills — reusable how-to workflows with progressive disclosure.
- [verify](https://brainmemory.ai/docs/commands/verify): Review and resolve memories pending verification — writes from untrusted sources held in quarantine.
- [sleep](https://brainmemory.ai/docs/commands/sleep): Full maintenance cycle: replay, homeostasis, consolidation, review reinforcement, pruning, and REM dreaming. Usually runs in the background.

## Advanced

- [Scoring Formula](https://brainmemory.ai/docs/advanced/scoring-formula): The v4 recall scoring formula: relevance, decayed strength, recency, spreading bonus, context match, and salience.
- [Spaced Reinforcement](https://brainmemory.ai/docs/advanced/spaced-reinforcement): How recall spacing affects strength boosts and decay rate improvements.
- [Sleep Cycle](https://brainmemory.ai/docs/advanced/sleep-cycle): Deep dive into the sleep maintenance cycle: replay, homeostasis, crystallization, and dreaming.
- [Cross-Agent Sharing](https://brainmemory.ai/docs/advanced/cross-agent): Share memories across Claude Code, OpenAI Codex CLI, OpenCode, and Antigravity agents.
- [Portable Sync](https://brainmemory.ai/docs/advanced/portable-sync): Git-based sync and encrypted export/import for cross-device memory portability.
- [Working Memory & Session Start](https://brainmemory.ai/docs/advanced/working-memory): How Brain feeds the context window at session start through a single budget-bounded aggregator that never overflows working memory.
- [Portable Skill Distribution](https://brainmemory.ai/docs/advanced/skill-distribution): Ship Brain as a portable agentskills.io SKILL.md folder that runs unmodified across Claude Code, Copilot, Cursor, Codex, Gemini CLI, and more.
- [Self-Hosting a Store](https://brainmemory.ai/docs/advanced/self-hosting): Run brain-store, an open reference server for the Brain store contract, and your own MCP connector in front of it.

## Reference

- [File Structure](https://brainmemory.ai/docs/reference/file-structure): Complete reference for the ~/.brain/ directory layout and file organization.
- [Memory File Format](https://brainmemory.ai/docs/reference/memory-format): YAML frontmatter schema and Markdown body format for memory files.
- [Configuration](https://brainmemory.ai/docs/reference/configuration): Configuration options for decay rates, scoring weights, and sync settings.
- [Changelog](https://brainmemory.ai/docs/reference/changelog): Release history and version notes for the Brain Memory plugin.

## Benchmarks

- [Overview](https://brainmemory.ai/docs/benchmarks): Controlled benchmark suite proving Brain Memory improves retrieval, contradiction handling, and token efficiency for AI coding agents.
- [Methodology](https://brainmemory.ai/docs/benchmarks/methodology): How retrieval is scored, why the judge is cross-family, distractor haystacks, and references to the 2025-2026 SOTA the design follows.
- [Scenarios](https://brainmemory.ai/docs/benchmarks/scenarios): The six benchmark scenarios — each describable in one sentence — with project fixtures, rubrics, and arm matrices.
- [Results](https://brainmemory.ai/docs/benchmarks/results): Current measurements from the benchmark suite, with raw JSON downloads.

## Blog

- [Ranking a poisoned memory lower is not a defense](https://brainmemory.ai/blog/ranking-is-not-a-defense) (2026-10-18): We planted one wrong answer per question in LongMemEval. Trust-weighted recall still put it first nine times in ten. Brain 0.5.0 keeps untrusted memories out until you approve them, treats remembered permissions as their own class, and checks every memory the agent cites.
- [We tried to add embeddings. Our own benchmark said no.](https://brainmemory.ai/blog/we-tried-embeddings) (2026-09-07): A real embedding model, given every advantage, failed to beat BM25 on a 1,021-memory corpus with 1,000 distractors. Here is the experiment, the numbers, and what would change our mind.
- [When a memory stops being true](https://brainmemory.ai/blog/when-a-memory-stops-being-true) (2026-08-08): Decay handles memories that fade. It doesn't handle memories that were true and then, on a specific day, weren't. Brain now models truth-based invalidation: supersede the old fact, keep it answerable, let the new one win.
- [One skill, every agent: Brain as a portable SKILL.md](https://brainmemory.ai/blog/one-skill-every-agent) (2026-08-08): Brain already installed natively into a handful of coding agents. Now it ships as a single portable Agent Skill folder that runs unmodified across ~40 clients — the ones we support, and the ones we've never heard of.
- [Closing the loop on memory poisoning: quarantine, audit, and rollback](https://brainmemory.ai/blog/quarantine-and-audit) (2026-08-07): The write-path gate stopped planted memories from entrenching. Now brain flags untrusted writes for review, detects the patterns an attack leaves behind, and can roll the whole brain back — all five OWASP ASI06 layers, shipped.
- [Introducing Brain Memory: a memory system that forgets on purpose](https://brainmemory.ai/blog/introducing-brain-memory) (2026-07-26): AI agents start every session at zero. The usual fixes treat memory as storage plus search. Brain models it the way remembering actually works — decay, reinforcement, association — in plain files you can read.
- [Provenance, not filtering: hardening brain against memory poisoning](https://brainmemory.ai/blog/provenance-memory-poisoning) (2026-07-26): A single email can plant a false memory in an AI agent and keep it there. Here is the attack, where brain was exposed, and the write-path gate we shipped in response.

## Optional

- [GitHub repository](https://github.com/omelas-tech/brain): source code and issues
- [npm package](https://www.npmjs.com/package/brain-memory): install with `npm install -g brain-memory`
- [Full documentation corpus](https://brainmemory.ai/llms-full.txt): every page concatenated as plain text