Ombre Brain provides a persistent, human-like long-term memory system for LLMs like Claude, addressing the limitation of stateless conversations. It allows AI models to retain context, experiences, and emotional nuances across interactions, enhancing conversational depth and continuity. The system is designed for users seeking to imbue their AI interactions with a sense of history and evolving memory, integrating seamlessly with Obsidian for knowledge management.

How It Works

Ombre Brain employs a unique approach by tagging memories with continuous emotional coordinates (Russell's valence/arousal model) rather than discrete labels. It leverages Obsidian-compatible Markdown for storage, enabling direct interaction with user knowledge bases. Core functionalities include a dual-channel search combining keyword fuzzy matching (rapidfuzz) with vector semantic similarity (embeddings), a modified Ebbinghaus forgetting curve for natural memory decay, and a "weight pool surfacing" mechanism where unresolved or emotionally intense memories actively resurface. It also features memory reconstruction that subtly adjusts recall based on current emotional state and optional LLM-powered "dehydration" for compressing and auto-tagging memories, with results cached locally.

Quick Start & Requirements

The simplest setup involves using the pre-built Docker image.

• Primary Install/Run:
  1. Install Docker Desktop.
  2. Create a working directory: mkdir ombre-brain && cd ombre-brain
  3. Download compose file: curl -O https://raw.githubusercontent.com/P0luz/Ombre-Brain/main/docker-compose.user.yml
  4. Create .env file with an API key (optional but recommended for full features): echo "OMBRE_API_KEY=your-key-here" > .env
  5. Pull and start: docker compose -f docker-compose.user.yml up -d
• Prerequisites: Docker Desktop, an optional Google AI Studio API key (for dehydration/tagging), and Claude Desktop for integration. An Obsidian Vault is optional; data can be stored locally.
• Requirements: Python 3.11+ (for source install).
• Links: Docker Hub (p0luz/ombre-brain:latest), Backup Gitea (https://git.p0lar1s.uk/P0lar1s/Ombre_Brain), Google AI Studio (aistudio.google.com/apikey).

Highlighted Details

• Emotional Tagging: Utilizes Russell's valence/arousal circumplex model for nuanced memory annotation.
• Dual-Channel Search: Combines keyword fuzzy matching with vector semantic similarity for robust retrieval.
• Natural Forgetting: Implements a configurable Ebbinghaus forgetting curve for memory decay.
• Obsidian Native: Stores memories as Markdown files with YAML frontmatter and auto-injected wikilinks.
• Memory Reconstruction: Adjusts valence display based on current mood, simulating cognitive bias.
• API Dehydration & Cache: LLM-powered compression and tagging with local SQLite caching to reduce API calls.
• Conversation History Import: Supports batch import from various LLM export formats.

Maintenance & Community

No specific details regarding maintainers, sponsorships, or community channels (like Discord/Slack) are provided in the README. The project appears actively developed, indicated by the detailed documentation and feature set.

Licensing & Compatibility

The project is released under the MIT License, permitting commercial use and modification with standard attribution requirements.

Limitations & Caveats

Full functionality, particularly LLM-powered dehydration and auto-tagging, requires an API key; free tiers are available but have limits. The free tier on Render is unsuitable due to lack of persistent storage. Cloudflare Tunnel's free tier has idle timeouts. Ombre Brain focuses on event-based memory, distinct from the LLM's core identity or preference memory.