# aura-turbo

**Compressed Persistent Memory for AI Agents**

> Give your AI assistant a memory that never forgets — and fits in your pocket.

aura-turbo is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that provides persistent, compressed memory storage for Claude and other AI assistants. Memories survive across sessions, are compressed with zlib for efficient storage, and are searchable by keyword and tag.

## Features

- **Persistent memory** — SQLite-backed storage that survives restarts
- **zlib compression** — Typical 3-5x compression on text content
- **Three memory levels** — `core` (permanent), `working` (7-day TTL), `ephemeral` (24h TTL)
- **Tag-based organization** — Categorize and retrieve memories by tag
- **Keyword search** — TF-IDF-style relevance scoring across all memories
- **Automatic expiry** — Ephemeral and working memories clean up after themselves
- **Deduplication** — Content-hash prevents storing identical memories twice
- **Zero external dependencies** — Uses only Python stdlib (zlib, sqlite3) plus the MCP SDK

## Installation

```bash
pip install aura-turbo
```

Or clone and run directly:

```bash
git clone https://github.com/aura-turbo/aura-turbo.git
cd aura-turbo
pip install -e .
```

## Quick Start

Run the server directly:

```bash
python server.py
```

### Claude Desktop Configuration

Add to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "aura-turbo": {
      "command": "python",
      "args": ["/path/to/aura-turbo/server.py"]
    }
  }
}
```

Or if installed via pip:

```json
{
  "mcpServers": {
    "aura-turbo": {
      "command": "aura-turbo"
    }
  }
}
```

### Custom Database Location

Set the `AURA_TURBO_DB` environment variable to use a custom database path:

```json
{
  "mcpServers": {
    "aura-turbo": {
      "command": "python",
      "args": ["/path/to/aura-turbo/server.py"],
      "env": {
        "AURA_TURBO_DB": "/path/to/my-memories.db"
      }
    }
  }
}
```

Default location: `~/.aura-turbo/memories.db`

## Tools

### `memory_store`
Store a memory with optional tags and importance level.

```
content: "The user prefers dark mode and uses vim keybindings"
tags: ["preferences", "editor"]
level: "core"
```

### `memory_recall`
Search memories by keyword or phrase. Returns ranked results.

```
query: "editor preferences"
limit: 5
```

### `memory_forget`
Delete a specific memory by ID.

```
memory_id: 42
```

### `memory_stats`
Show storage statistics — total memories, compression ratio, space saved.

### `memory_search_by_tag`
Find all memories with a specific tag.

```
tag: "preferences"
```

### `memory_clear_expired`
Remove ephemeral memories older than 24h and working memories older than 7 days. Core memories are never removed.

## How Compression Works

aura-turbo uses Python's built-in `zlib` library (which implements DEFLATE/gzip compression) to compress memory content before storing it in SQLite.

| Content Type | Typical Ratio |
|---|---|
| English prose | 3-4x |
| Code snippets | 3-5x |
| JSON/structured data | 4-6x |
| Already compressed | ~1x |

A 1KB conversation summary compresses to ~250-300 bytes. Over hundreds of memories, this adds up to significant space savings while keeping everything in a single portable SQLite file.

## Comparison

| Feature | aura-turbo | Mem0 | Custom RAG |
|---|---|---|---|
| Price | **Free** | $249/mo | Varies |
| Storage | Local SQLite | Cloud | Cloud/Local |
| Dependencies | MCP SDK only | Many | Many |
| Compression | zlib (3-5x) | None | None |
| Setup time | 1 minute | Account setup | Hours |
| Privacy | **100% local** | Cloud | Depends |
| MCP native | Yes | No | No |

## Architecture

```
Claude/AI <--MCP--> server.py <--> storage.py <--> SQLite + zlib
                                        |
                                   ~/.aura-turbo/
                                    memories.db
```

## License

MIT
