Aiana

Personal AI Operations Memory for Claude Code

Aiana transforms Claude Code from stateless sessions into a compound learning system. It captures conversations, embeds them as vectors, and injects relevant context at session start—so your AI assistant remembers YOUR patterns.

The Vision

Traditional: Sessions → Do tasks → Forget
With Aiana:  Sessions → Do tasks → Remember → Improve → Compound

Every session makes future sessions better. Your workflows get encoded. Your preferences persist. Claude learns YOUR way of working.

Architecture

flowchart TB
    subgraph CC["🖥️ Claude Code"]
        sessions["Sessions & Conversations"]
    end

    subgraph AIANA["🧠 AIANA - Memory Layer"]
        direction TB
        capture["📥 Session Capture"]
        embed["🔢 Embedding Engine<br/><i>all-MiniLM-L6-v2</i>"]
        inject["💉 Context Injector"]
        mcp["🔌 MCP Server"]
    end

    subgraph STORAGE["💾 Storage Backends"]
        direction LR
        sqlite[("📄 SQLite<br/>FTS5 Full-Text")]
        redis[("⚡ Redis<br/>Session Cache")]
        mem0[("🧠 Mem0<br/>AI Memory")]
        qdrant[("🔮 Qdrant<br/>Vector Search")]
    end

    CC -->|"hooks API"| capture
    capture --> embed
    embed --> sqlite
    embed --> redis
    embed --> mem0
    mem0 --> qdrant

    sqlite --> inject
    redis --> inject
    mem0 --> inject

    inject -->|"context block"| CC
    mcp <-->|"tools"| CC

    style AIANA fill:#7C3AED,color:#fff
    style CC fill:#D97706,color:#fff
    style sqlite fill:#0EA5E9,color:#fff
    style redis fill:#DC2626,color:#fff
    style mem0 fill:#EC4899,color:#fff
    style qdrant fill:#059669,color:#fff

Features

Storage & Search

SQLite with FTS5 - Session transcripts, full-text search
Redis caching - Fast session state, context cache, preferences
Qdrant vectors - Semantic search via sentence-transformers
Mem0 integration - Enhanced AI memory with automatic extraction and deduplication

Intelligence

Context injection - Auto-inject relevant memories at session start
User preferences - Persistent (static) and recent (dynamic) prefs
Semantic search - Find memories by meaning, not just keywords
Mem0 memory management - Automatic memory consolidation and relevance scoring

Integration

MCP server mode - Expose memory tools directly to Claude
Hook-based capture - Official Claude Code hooks API
File watcher - Docker-compatible monitoring mode
Auto-bootstrap - One-and-done preference loading on first install

Privacy

100% local - All data stays on your machine
No cloud sync - Nothing leaves your system
Read-only mounts - Docker uses read-only access to Claude data

Quick Start

Docker Compose (Recommended)

# Clone repository
git clone https://github.com/ry-ops/aiana
cd aiana

# Start full stack (Aiana + Redis + Qdrant)
docker compose up -d

# Check status
docker compose exec aiana aiana status

# Search memories
docker compose exec aiana aiana memory search "authentication"

Local Installation

# Install with all features
pip install -e ".[all]"

# Or minimal install
pip install -e .

# Install Claude Code hooks (auto-loads development preferences)
aiana install

# Start monitoring
aiana start

One-and-Done: The aiana install command automatically bootstraps your development preferences into memory. No manual configuration needed - your standards are immediately active across all projects.

CLI Commands

Session Management

# List recent sessions
aiana list --limit 10

# View a session
aiana show <session-id>

# Search full-text
aiana search "database migration"

# Export session
aiana export <session-id> --format markdown

Memory Operations

# Semantic search
aiana memory search "how did I fix the auth bug"

# Add a memory manually
aiana memory add "cortex uses uv for Python deps" --type pattern

# Recall context for a project
aiana memory recall git-steer

Preferences

# Add permanent preference
aiana prefer "Uses conventional commits"

# Add temporary/recent context
aiana prefer "Working on Aiana docs" --temporary

Bootstrap

# Force reload development preferences
aiana bootstrap --force

# Reset bootstrap marker (allows re-bootstrap on next install)
aiana bootstrap --reset

MCP Server

# Start MCP server
aiana mcp

# Check system status
aiana status

MCP Server Tools

When running as an MCP server, Aiana exposes these tools to Claude:

Tool	Description
`memory_search`	Semantic search across memories
`memory_add`	Save a memory or note
`memory_recall`	Get context for a project
`memory_feedback`	Rate recalled memories (helpful/not helpful/harmful)
`feedback_summary`	Get summary of recall quality patterns
`session_list`	List recorded sessions
`session_show`	View session details
`preference_add`	Add user preferences
`aiana_status`	System health check

Claude Desktop Integration

{
  "mcpServers": {
    "aiana": {
      "command": "aiana",
      "args": ["mcp"]
    }
  }
}

Docker Configuration

Full Stack (docker-compose.yml)

services:
  aiana:
    image: ry-ops/aiana:latest
    depends_on:
      - redis
      - qdrant
    volumes:
      - ~/.claude:/home/aiana/.claude:ro
      - aiana-data:/home/aiana/.aiana
    ports:
      - "8765:8765"  # MCP server
    environment:
      - REDIS_URL=redis://redis:6379
      - QDRANT_URL=http://qdrant:6333

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes

  qdrant:
    image: qdrant/qdrant:latest
    volumes:
      - qdrant-data:/qdrant/storage

volumes:
  aiana-data:
  qdrant-data:

Environment Variables

Variable	Description	Default
`TZ`	Timezone	`UTC`
`REDIS_URL`	Redis connection URL	`redis://localhost:6379`
`QDRANT_URL`	Qdrant server URL	`http://localhost:6333`
`AIANA_MCP_PORT`	MCP server port	`8765`
`AIANA_EMBEDDING_MODEL`	Embedding model	`all-MiniLM-L6-v2`

Mem0 Integration

AIANA v1.1.0 integrates Mem0 for enhanced AI memory management.

Why Mem0?

Automatic memory extraction - Extracts key information from conversations
Deduplication - Consolidates related memories automatically
Relevance scoring - Built-in scoring for better retrieval
46k+ stars - Active community, well-maintained

Integration Strategy

We use the Wrapper Pattern with pinned versions:

# Pinned to major version - allows patches, blocks breaking changes
"mem0ai>=1.0.3,<2.0"

┌─────────────────────────────────────────────────┐
│              AIANA Storage Layer                │
├─────────────────────────────────────────────────┤
│                                                 │
│   Mem0Storage  ──────►  QdrantStorage           │
│   (primary)             (fallback)              │
│       │                      │                  │
│       ▼                      ▼                  │
│   ┌───────┐              ┌───────┐              │
│   │ Mem0  │──────────────│Qdrant │              │
│   │  API  │   uses       │  API  │              │
│   └───────┘              └───────┘              │
│                                                 │
└─────────────────────────────────────────────────┘

Benefits:

Isolation - Mem0 API changes stay in Mem0Storage wrapper
Fallback - If Mem0 fails, QdrantStorage takes over
Testability - Can mock wrapper for testing
Swappability - Replace Mem0 without touching other code

See ADR-001 for full rationale.

Configuration

Configuration file: ~/.aiana/config.yaml

storage:
  type: sqlite
  path: ~/.aiana/conversations.db

recording:
  include_tool_results: true
  include_thinking: false
  redact_secrets: true

retention:
  days: 90
  max_sessions: 1000

privacy:
  encrypt_at_rest: false

How Context Injection Works

On every SessionStart, Aiana:

Loads your profile - Static preferences you've saved
Fetches project context - Recent work in this project
Searches semantically - Finds relevant memories
Injects context - Adds <aiana-context> block

<aiana-context>
## User Preferences (Persistent)
- Prefers TypeScript over JavaScript
- Uses ESLint flat config (v9+)
- Commits with conventional format

## Project: git-steer
### Recent Activity
- Fixed 9 security vulnerabilities
- Updated to vitest 4.x
- Created blog post series

## Recent Context
- Working on Aiana documentation
</aiana-context>

Claude sees this context and adapts to YOUR patterns.

Documentation

Architecture - Technical design and components
Storage Backends - SQLite, Redis, Qdrant configuration
MCP Server - MCP integration and tools
Context Injection - How memory injection works
Claude Code Internals - File formats, hooks, APIs
TOS Compatibility - Legal compliance

Architecture Decisions

ADR-001: Dependency Integration Strategy - Wrapper pattern for third-party libs

Privacy & Security

Aiana is designed with privacy as a core principle:

Local Only - All data stored on your machine
No Cloud Sync - Data never leaves your system
User Control - You decide what gets recorded
Read-Only Access - Docker mounts Claude directory as read-only
Non-Root Container - Runs as unprivileged user

Roadmap

Related Projects

ry-ops ecosystem:

git-steer - GitHub autonomy engine via MCP
cortex - Multi-agent AI system

Community tools:

ccusage - Cost/token tracking
claude-code-log - JSONL to HTML converter

Contributing

Contributions welcome! Please read the documentation and open an issue before submitting PRs.

License

MIT License - see LICENSE file for details.

Repository: github.com/ry-ops/aiana

Blog Post: Personal AI Operations Memory

Status: Phase 2.6 Complete - Auto-Bootstrap Ready

Version: v1.2.0

Updated: 2026-02-04

Changelog

v1.2.0 (2026-02-04)

Auto-Bootstrap: Automatically load development preferences on first aiana install
Added aiana bootstrap command for manual preference management
Bundled bootstrap/user-preferences.md with development standards
Cross-project memory by default (user-level, not project-isolated)
One-and-done installation experience

v1.1.0 (2026-02-04)

Added Mem0 integration for enhanced AI memory management
Automatic memory extraction from conversations
Memory consolidation and deduplication
Mem0 as primary memory backend with Qdrant fallback
Updated CLI commands to support Mem0
Updated MCP server tools for Mem0
Implemented wrapper pattern with pinned dependency (>=1.0.3,<2.0)
Added ADR-001: Dependency Integration Strategy

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github		.github
assets		assets
bootstrap		bootstrap
docs		docs
src/aiana		src/aiana
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
Aiana.png		Aiana.png
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
aiana1.png		aiana1.png
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

ry-ops/aiana

Folders and files

Latest commit

History

Repository files navigation

Aiana

The Vision

Architecture

Features

Storage & Search

Intelligence

Integration

Privacy

Quick Start

Docker Compose (Recommended)

Local Installation

CLI Commands

Session Management

Memory Operations

Preferences

Bootstrap

MCP Server

MCP Server Tools

Claude Desktop Integration

Docker Configuration

Full Stack (docker-compose.yml)

Environment Variables

Mem0 Integration

Why Mem0?

Integration Strategy

Configuration

How Context Injection Works

Documentation

Architecture Decisions

Privacy & Security

Roadmap

Related Projects

Contributing

License

Changelog

v1.2.0 (2026-02-04)

v1.1.0 (2026-02-04)

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors 2

Languages

Packages