# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Fading Memories** - Hierarchical conversation compression with natural memory decay

A memory system for AI conversations that mimics human memory: vivid recent details progressively compress into summaries, with frequently accessed memories staying sharp while neglected ones gradually fade into oblivion.

### Core Concept

```
Time 0:        [Full detailed conversation - 50,000 tokens]
                              │
Time 1:        [Summary L1 - 5,000 tokens] ──→ [Details accessible via links]
                              │
Time 2:        [Summary L2 - 500 tokens] ──→ [L1 accessible] ──→ [Details if accessed]
                              │
Time 3:        [Summary L3 - 50 tokens] ──→ [Faded memories pruned if never accessed]
```

### Memory Decay Model

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  Strength                                                   │
│     │                                                       │
│  ███│████                                                   │
│  ███│████████                                               │
│  ███│████████████          ← Accessed memories stay vivid  │
│  ███│████████████████                                       │
│  ███│█████████████████████                                  │
│  ███│████████████████████████████                           │
│     │                            ████████                   │
│     │                                    ████── → 0 (fade)  │
│     └─────────────────────────────────────────────────────  │
│                           Time                              │
└─────────────────────────────────────────────────────────────┘
```

**Factors affecting decay:**
- **Access frequency** - Viewed memories decay slower
- **Importance markers** - Explicitly marked memories persist
- **Reference count** - Memories linked by other memories stay
- **Recency** - Recent memories have higher base strength

### Architecture

```
src/fading_memories/
├── __init__.py
├── __main__.py              # CLI entry point
├── models/
│   ├── memory.py            # Memory node (content, strength, links)
│   ├── conversation.py      # Conversation container
│   └── hierarchy.py         # Memory tree structure
├── compression/
│   ├── summarizer.py        # LLM-based summarization
│   ├── linker.py            # Extract/preserve important links
│   └── strategies.py        # Compression strategies
├── decay/
│   ├── strength.py          # Strength calculation
│   ├── scheduler.py         # When to compress/prune
│   └── pruner.py            # Remove faded memories
├── storage/
│   ├── sqlite.py            # SQLite backend
│   └── export.py            # Export to markdown/json
└── api/
    ├── server.py            # REST API
    └── routes.py            # Endpoints
```

### Data Model

```python
class Memory:
    id: str                    # Unique identifier
    content: str               # The actual content
    level: int                 # Compression level (0=raw, 1=summary, etc.)
    parent_id: str | None      # Link to more detailed version
    children: list[str]        # Links to compressed versions

    # Decay tracking
    strength: float            # 0.0 to 1.0, below threshold = prune
    created_at: datetime
    last_accessed: datetime
    access_count: int

    # Metadata
    importance: float          # User-marked importance
    tokens: int                # Token count
    tags: list[str]

class Conversation:
    id: str
    memories: list[Memory]     # Hierarchy of memories
    root_id: str               # Most compressed summary

    def access(self, memory_id: str) -> Memory:
        """Access a memory, boosting its strength."""

    def drill_down(self, memory_id: str) -> Memory | None:
        """Get more detailed parent memory if it exists."""

    def summarize(self) -> str:
        """Get current top-level summary."""
```

### Compression Flow

1. **Ingest** - Raw conversation comes in
2. **Chunk** - Split into semantic chunks
3. **Summarize** - Create L1 summary, link to chunks
4. **Store** - Save with initial strength = 1.0
5. **Decay** - Over time, strength decreases
6. **Access** - When accessed, strength boosts
7. **Compress** - When strength drops, create L2 summary
8. **Prune** - When strength ≈ 0 and no children need it, delete

### API Endpoints

```
POST /conversations              # Create new conversation
GET  /conversations/:id          # Get conversation summary
GET  /conversations/:id/memory/:mid   # Access specific memory (boosts strength)
POST /conversations/:id/drill    # Drill down to more detail
GET  /conversations/:id/tree     # Get full memory hierarchy
POST /decay/run                  # Trigger decay cycle
```

### CLI Usage

```bash
# Add a conversation
fading-memories add conversation.txt

# View current summary
fading-memories view <conversation-id>

# Drill into details
fading-memories drill <memory-id>

# Run decay cycle
fading-memories decay --threshold 0.1

# Export before it fades
fading-memories export <conversation-id> --format markdown
```

## Development Commands

```bash
# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Start API server
fading-memories serve --port 8080

# Run decay scheduler
fading-memories daemon
```

## Key Design Decisions

1. **Hierarchical, not flat** - Memories link to more/less detailed versions
2. **Lazy deletion** - Only prune when storage pressure or explicitly requested
3. **Boost on access** - Reading a memory reinforces it
4. **Configurable decay** - Different decay curves for different use cases
5. **Export before fade** - Always allow exporting before deletion

## Use Cases

- **Long-running AI conversations** - Keep context without unbounded growth
- **Chat history archival** - Compress old chats while keeping them searchable
- **Meeting notes** - Detailed notes fade to action items over time
- **Learning systems** - Spaced repetition based on access patterns

## Documentation

Documentation lives in `docs/` (symlink to centralized docs system).

Quick reference:
- Edit files in `docs/` folder
- Use `public: true` frontmatter for public-facing docs
- Deploy: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh fading-memories --deploy`