Metadata-Version: 2.4
Name: oubli
Version: 0.1.0
Summary: Fractal memory system for Claude Code
Project-URL: Homepage, https://github.com/dremok/oubli
Project-URL: Repository, https://github.com/dremok/oubli
Author: Max Leander
License: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,llm,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: lancedb>=0.4.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyarrow>=14.0.0
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
Description-Content-Type: text/markdown

# Oubli

<img width="35%" alt="image" src="https://github.com/user-attachments/assets/4a3784f7-c139-4af6-8bf8-38c61df1fc7b" />

<br /><br />

**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

- **Core Memory** - Essential facts about you (~2K tokens), loaded in every conversation
- **Persistent Storage** - Memories survive across sessions, stored locally in LanceDB
- **Smart Import** - Import your Claude.ai memory export with one command
- **Auto-Save** - Saves memories at session end and before context compaction
- **Fractal Synthesis** - Automatically consolidates raw memories into higher-level insights
- **Proactive Memory** - Claude searches and saves automatically, no prompting needed
- **Quiet Operation** - Memory operations happen silently in the background
- **Local-First** - No external services, no API keys, your data stays on your machine

## Installation

```bash
pip install oubli
oubli setup
```

Then restart Claude Code.

### Requirements

- Python 3.10+
- [Claude Code](https://claude.ai/code) CLI installed

### Uninstall

```bash
oubli uninstall
pip uninstall oubli
```

### What Gets Installed

| Component | Location | Description |
|-----------|----------|-------------|
| MCP Server | `claude mcp` | 13 memory tools (save, search, synthesize, etc.) |
| Hooks | `~/.claude/settings.json` | UserPromptSubmit, PreCompact, Stop |
| Slash Command | `~/.claude/commands/` | `/clear-memories` |
| Instructions | `~/.claude/CLAUDE.md` | How Claude should use the memory system |
| Data | `~/.oubli/` | LanceDB database + Core Memory file |

## Usage

After installation, restart Claude Code. Your Core Memory will be automatically loaded in every conversation.

### Import Existing Memories

Paste your Claude.ai memory export and ask:
> "Import this into my memory"

Claude will parse it into structured memories and optionally create your Core Memory.

### Natural Interaction

Just talk naturally:
- "Remember that I prefer TypeScript over JavaScript"
- "What do you know about my work?"
- "I no longer work at Spotify, update your memory"

### Slash Commands

- `/clear-memories` - Clear all memories (requires confirmation)

## How It Works

```
           ┌─────────────────────────────────────────┐
           │            CORE MEMORY                  │
           │    (~2K tokens, always in context)      │
           │                                         │
           │  The essential "you" - personality,     │
           │  key preferences, life context, work    │
           └─────────────────────┬───────────────────┘
                                 │ (distilled from)
                                 ▼
Level 1+   ○ "Deeply appreciates jazz guitar, especially fusion"
(insights)  ╱╲
           ╱  ╲
Level 0   ○ ○ ○ ○  Raw memories from conversations
(raw)
```

- **Core Memory**: Always loaded, contains the most important stable facts
- **Level 0**: Raw memories from conversations with full context
- **Level 1+**: Synthesized insights from multiple raw memories

## Data Storage

All data is stored locally in `~/.oubli/`:
- `memories.lance/` - LanceDB database
- `core_memory.md` - Your Core Memory (human-readable, editable)

## MCP Tools

Oubli provides 13 MCP tools for memory operations:

| Tool | Description |
|------|-------------|
| `memory_save` | Save a new memory |
| `memory_search` | Search memories (prefers higher-level insights) |
| `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 |
| `memory_update` | Update an existing memory |
| `memory_delete` | Delete a memory |
| `memory_import` | Bulk import memories |
| `memory_synthesize` | Create Level 1+ insight from raw memories |
| `memory_get_synthesis_candidates` | Find topics ready for synthesis |
| `core_memory_get` | Get Core Memory content |
| `core_memory_save` | Save Core Memory content |

## Development

```bash
# Clone and install in development mode
git clone https://github.com/dremok/oubli.git
cd oubli
pip install -e .
oubli setup

# Run tests
python -c "from oubli.storage import MemoryStore; store = MemoryStore(); print(store.get_stats())"

# Check MCP tools
python -c "from oubli.mcp_server import mcp; print([t.name for t in mcp._tool_manager._tools.values()])"
```

## License

MIT
