oubli 0.2.4

Fractal memory system for Claude Code

Oubli

Oubli: French for "forgetting." (Also a West African fruit so sweet it makes babies forget their mother's milk.)

A memory system that never forgets. Persistent fractal memory for Claude Code.

Features

• Fractal in Both Directions - Synthesize raw memories into insights, drill down from insights to source details
• Hybrid Search - Combines BM25 keyword search + semantic embeddings for intelligent retrieval
• Core Memory - Essential facts about you (~2K tokens), loaded in every conversation
• Proactive Memory - Claude searches and saves automatically, no prompting needed
• Immediate Updates - Family, work, and identity changes update Core Memory instantly
• Quiet Operation - Memory operations happen silently in the background
• Local-First - All data stays on your machine, no external services

Installation

pip install oubli
oubli setup

Then restart Claude Code. The embedding model (~80MB) downloads on first use.

Requirements

• Python 3.10+
• Claude Code CLI installed

Uninstall

oubli uninstall
pip uninstall oubli

How It Works

Fractal Memory Hierarchy

The memory system is fractal in both directions:

           ┌─────────────────────────────────────────┐
           │            CORE MEMORY                  │
           │    (~2K tokens, always in context)      │
           │                                         │
           │  Identity, family, work, preferences    │
           └─────────────────────┬───────────────────┘
                                 │
                    ▲ synthesis  │  drill-down ▼
                                 │
Level 2    ○ "Deeply technical, values efficiency"
            ╲
Level 1    ○ ○ "Loves jazz fusion"  "Python expert"
            ╲│
Level 0    ○○○○ Raw memories with full conversation text

• Upward (Synthesis): Raw memories consolidate into higher-level insights
• Downward (Drill-down): From any insight, retrieve its source memories for full detail

Level	Contains	Use Case
Core Memory	Essential identity (~2K tokens)	Always loaded, answers most questions
Level 1+	Synthesized insights	Quick context without full details
Level 0	Raw memories + full conversation	When you need exact quotes or specifics

Hybrid Search

Oubli uses LanceDB's hybrid search combining:

• BM25 Full-Text Search - Finds keyword matches
• Semantic Embeddings - Finds conceptually related content (via sentence-transformers)
• RRF Reranking - Merges both result sets intelligently

Example: Searching "jazz music" finds memories about "Pat Metheny" and "fusion harmonies" even without exact keyword matches.

Synthesis (Bottom-Up)

Run /synthesize to consolidate raw memories into insights:

1. Merge duplicates - Similar memories at each level are combined (85% Jaccard threshold)
2. Group by topic - Related memories clustered together
3. Create insights - Level 1+ memories synthesize the patterns
4. Update Core Memory - Regenerated from highest-level insights

Drill-Down Retrieval (Top-Down)

When you need more detail than a high-level insight provides:

1. Search returns synthesized insights first (compact, high-signal)
2. Get parents retrieves the source memories that formed an insight
3. Get full text retrieves the complete conversation from a Level 0 memory

Nothing is ever lost - every insight links back to its source memories.

Usage

Natural Interaction

Just talk naturally. Claude handles memory operations silently:

• "I prefer TypeScript over JavaScript" → Saved automatically
• "What do you know about my work?" → Searches memory
• "I no longer work at Spotify" → Deletes old, saves new, updates Core Memory

Import Existing Memories

Paste your Claude.ai memory export and ask:

"Import this into my memory"

Claude parses it into structured memories and optionally creates your Core Memory.

Slash Commands

• /synthesize - Run full synthesis: merge duplicates, create insights, update Core Memory
• /clear-memories - Clear all memories (requires confirmation)

Data Storage

All data stored locally in ~/.oubli/:

File	Description
memories.lance/	LanceDB database with vector embeddings
core_memory.md	Your Core Memory (human-readable, editable)

What Gets Installed

Component	Location	Description
MCP Server	claude mcp	15 memory tools
Hooks	~/.claude/settings.json	UserPromptSubmit, PreCompact, Stop
Commands	~/.claude/commands/	/clear-memories, /synthesize
Instructions	~/.claude/CLAUDE.md	How Claude uses the memory system

MCP Tools

Retrieval

Tool	Description
memory_search	Hybrid search (BM25 + semantic)
memory_get	Get full details including conversation text
memory_get_parents	Drill down from synthesis to source memories
memory_list	List memories by level
memory_stats	Get memory statistics

Storage

Tool	Description
memory_save	Save a new memory (auto-embeds)
memory_import	Bulk import memories
memory_update	Update an existing memory
memory_delete	Delete a memory

Synthesis

Tool	Description
memory_synthesis_needed	Check if synthesis should run (threshold: 5)
memory_prepare_synthesis	Merge duplicates, return groups for synthesis
memory_synthesize	Create Level 1+ insight from parent memories
memory_dedupe	Manual duplicate cleanup

Core Memory

Tool	Description
core_memory_get	Get Core Memory content
core_memory_save	Save Core Memory content

Development

git clone https://github.com/dremok/oubli.git
cd oubli
pip install -e .
oubli setup

# Test storage
python -c "
from oubli.storage import MemoryStore
store = MemoryStore()
print('Embeddings:', store.embeddings_enabled())
store.add(summary='Test memory', topics=['test'])
print(store.search('test'))
"

License

MIT