Overview
BrainLayer is a local-first persistent memory system for MCP agents. It preserves decisions, learnings, corrections, preferences, and prior work across restarts, context compaction, and separate sessions in a single local SQLite database.
The system combines semantic retrieval, keyword search, and a knowledge graph so agents can recover relevant context rather than rediscovering earlier work. It is free and open source, with a Python package for installation and an optional macOS companion app called BrainBar.
Key Features
- Hybrid search combines bge-large embeddings with FTS5 keyword matching through Reciprocal Rank Fusion.
- Knowledge ingestion extracts entities, relationships, and action items from stored content.
- Memory storage applies automatic type detection, importance scoring, and per-agent scoping.
- Lifecycle controls can update, supersede, enrich, or archive chunks while preserving history and an audit trail.
- Agent subscriptions deliver notifications for matching tags and allow processed messages to be acknowledged.
- Backup and maintenance operations support SQLite snapshots and rebuilding the trigram search index.
MCP Tool Surface
BrainLayer exposes 17 tools on its live surface. Daily operations include searching memories, storing new context, recalling session-aware history and plans, and expanding a search result with surrounding context. Additional tools cover entity and person lookup, deep ingestion, tag management, enrichment, chunk lifecycle operations, agent notifications, backup, and index maintenance.
Search output uses a compact formatter that omits empty metadata such as missing tags. The secondary Python transport exposes 13 tools, including the Python-only session resume operation.
Setup and Compatibility
Installation uses the BrainLayer Python package, followed by initialization of the MCP configuration and local database. A watch process then handles indexing and optional BrainBar capture flows.
BrainLayer works with MCP clients including Claude Code, Cursor, Zed, VS Code, Codex, Kiro, and Gemini CLI. These clients access the same memory layer, while BrainBar provides quick capture, a live dashboard, a knowledge graph viewer, and the shared formatter through a Unix socket on macOS. BrainBar requires the BrainLayer MCP server.
Architecture
The storage architecture uses SQLite with sqlite-vec. Its hybrid retrieval pipeline combines vector and keyword results, while entity relations connect knowledge accumulated across conversations. Enrichment can add summaries, extracted entities, action items, and graph links to existing chunks.