# Kiro Total Recall

Ever told Kiro "like we discussed yesterday" only to realize... it has no idea?

**Total Recall** gives Kiro the memory it's missing.

## The Problem

1. **Sessions Are Isolated**: Each Kiro session starts fresh. Yesterday's architecture discussion? Gone.
2. **Projects Don't Share Knowledge**: Your preferences (testing style, package managers, patterns) aren't remembered across projects.
3. **CLI and IDE Are Separate**: Conversations in Kiro CLI don't connect to Kiro IDE.

**Total Recall indexes every Kiro conversation and provides semantic search.** Find discussions by *meaning*, not just keywords.

## Quickstart

### As a Kiro Power (Recommended, IDE only)

1. In Kiro IDE: Powers panel → **Add power from GitHub**
2. Enter: `https://github.com/danilop/kiro-total-recall`
3. The power activates automatically when you mention "recall", "remember", or "past conversation"

### Manual MCP Setup (CLI and IDE)

Add to `~/.kiro/settings/mcp.json` (this config is shared by both CLI and IDE):

```json
{
  "mcpServers": {
    "total-recall": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/danilop/kiro-total-recall", "kiro-total-recall"]
    }
  }
}
```

**Restart Kiro CLI/IDE** after adding. MCP servers are only loaded at startup.

### Verify Installation

In Kiro CLI: `/mcp` should list `total-recall`

In Kiro IDE: Check the MCP Servers panel

## How It Works

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         Kiro CLI & IDE                                  │
│  ┌──────────────────────────┐    ┌──────────────────────────────────┐   │
│  │  CLI: SQLite DB          │    │  IDE: .chat JSON files           │   │
│  │  ~/Library/App Support/  │    │  ~/Library/App Support/Kiro/     │   │
│  │  kiro-cli/data.sqlite3   │    │  User/globalStorage/.../*.chat   │   │
│  └────────────┬─────────────┘    └─────────────┬────────────────────┘   │
│               └────────────────┬───────────────┘                        │
│                                ▼                                        │
│                    ┌───────────────────────┐                            │
│                    │   Unified Loader      │                            │
│                    └───────────┬───────────┘                            │
└────────────────────────────────┼────────────────────────────────────────┘
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      Kiro Total Recall                                  │
│  ┌─────────┐    ┌──────────┐    ┌─────────┐    ┌────────────────────┐   │
│  │ loader  │───▶│ indexer  │───▶│  query  │───▶│  MCP server        │   │
│  │ CLI+IDE │    │ 384-dim  │    │ cosine  │    │  4 search tools    │   │
│  └─────────┘    └────┬─────┘    └─────────┘    └────────────────────┘   │
│                      ▼                                                  │
│         ~/.cache/kiro-total-recall/embeddings.pkl                       │
└─────────────────────────────────────────────────────────────────────────┘
```

### The Index: Making Search Fast

On first search, Total Recall:

1. **Loads** all messages from CLI (SQLite) and IDE (.chat files)
2. **Embeds** each message using [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) (384-dimensional vectors)
3. **Caches** embeddings to `~/.cache/kiro-total-recall/embeddings.pkl`

Subsequent searches are fast because:

- **Fingerprinting**: Only rebuilds when conversations change
- **Incremental updates**: New messages get embedded; existing embeddings loaded from cache
- **Hash-based deduplication**: Same text = same embedding (no recomputation)

## Features

- **Semantic Search**: Find by meaning, not just keywords
- **Dual Source**: Searches both CLI and IDE conversations
- **Context Windows**: See surrounding messages for each match
- **Date Filtering**: Filter by time range (ISO 8601)
- **Incremental Indexing**: Only processes new conversations
- **Memory Limits**: Configurable RAM usage (default: 1/3 of RAM)

## MCP Tools

| Tool | Scope | Use Case |
|------|-------|----------|
| `search_project_history` | Current workspace | Bugs, decisions in *this* codebase |
| `search_global_history` | All workspaces | Preferences, patterns across *all* work |
| `search_cli_history` | CLI only | Kiro CLI conversations |
| `search_ide_history` | IDE only | Kiro IDE conversations |

### Parameters

All tools accept:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `query` | required | Keywords or sentence to search |
| `after` | none | Filter to messages on/after this date (inclusive). ISO 8601 format. |
| `before` | none | Filter to messages before this date (exclusive). ISO 8601 format. |
| `context_size` | 3 | Messages before AND after each match |
| `threshold` | 0.2 | Minimum similarity (0-1, higher = stricter) |
| `max_results` | 10 | Maximum results to return |
| `offset` | 0 | Skip results (for pagination) |

### Date Filtering Examples

```python
# Messages from a specific day
search_project_history(query="auth bug", after="2025-01-15", before="2025-01-16")

# Messages from the past week
search_project_history(query="refactoring", after="2025-01-25")

# Messages in January
search_project_history(query="database", after="2025-01-01", before="2025-02-01")
```

### Response Structure

```json
{
  "results": [
    {
      "matched_message": {
        "role": "assistant",
        "content": "To fix the authentication bug...",
        "timestamp": "2025-01-15T10:30:00",
        "workspace": "/Users/dev/myproject",
        "session_id": "abc123",
        "uuid": "msg-456",
        "source": "cli"
      },
      "score": 0.8542,
      "context": [
        {"role": "user", "content": "How do I fix this auth bug?", "timestamp": "...", "is_match": false},
        {"role": "assistant", "content": "To fix the authentication bug...", "timestamp": "...", "is_match": true}
      ]
    }
  ],
  "query": "authentication bug fix",
  "total_matches": 25,
  "offset": 0,
  "has_more": true,
  "hint": "Showing 1-10 of 25 matches. Use offset: 10 for more."
}
```

## Usage Examples

Just ask naturally:

```
"How did we fix that auth bug?"
"What did we discuss about the database schema?"
"What's my usual approach to error handling?"
"Find our React component discussions from last week"
```

Or use tools directly:

```python
search_project_history(query="authentication bug fix")
search_global_history(query="React component patterns")
search_cli_history(query="deployment", after="2025-01-01")
```

## Configuration

Create `~/.config/kiro-total-recall/config.toml` to customize:

```toml
[sources.cli]
enabled = true
paths = [
    "~/Library/Application Support/kiro-cli/data.sqlite3",
    "~/.local/share/kiro-cli/data.sqlite3",
    "~/AppData/Roaming/kiro-cli/data.sqlite3",
]

[sources.ide]
enabled = true
patterns = [
    "~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/*/*.chat",
    "~/.config/Kiro/User/globalStorage/kiro.kiroagent/*/*.chat",
    "~/AppData/Roaming/Kiro/User/globalStorage/kiro.kiroagent/*/*.chat",
]

[embedding]
model = "all-MiniLM-L6-v2"
cache_dir = "~/.cache/kiro-total-recall"

[search]
default_threshold = 0.2
default_max_results = 10
default_context_window = 3

[memory]
fraction = 0.33  # Use 1/3 of RAM
# limit_mb = 512  # Or set explicit limit
```

## Memory Management

Total Recall limits in-memory index size to prevent excessive memory usage. By default, it uses 1/3 of physical RAM. When the limit is reached, the oldest sessions are excluded from the index (newest sessions are kept).

| Variable | Description | Default |
|----------|-------------|---------|
| `KIRO_RECALL_MEMORY_LIMIT_MB` | Override memory limit in MB | 1/3 of RAM |
| `KIRO_RECALL_NO_MEMORY_LIMIT` | Set to any value to disable limit | - |

## Testing

```bash
# Test server starts
uvx kiro-total-recall
# Ctrl+C to exit

# Test search directly
uv run python -c "
from kiro_total_recall.query import search_conversations
result = search_conversations(query='bug fix', max_results=3)
print(f'Found {result.total_matches} matches')
"
```

## Project Structure

```
kiro-total-recall/
├── POWER.md                      # Kiro Power manifest + steering
├── mcp.json                      # MCP server config for Power
├── config.default.toml           # Default configuration
├── src/kiro_total_recall/
│   ├── server.py                 # FastMCP server, tool definitions
│   ├── query.py                  # Search engine, deduplication
│   ├── indexer.py                # Embedding, caching, fingerprinting
│   ├── loader.py                 # Unified loader (CLI + IDE)
│   ├── cli_loader.py             # SQLite parsing for CLI
│   ├── ide_loader.py             # JSON parsing for IDE .chat files
│   ├── config.py                 # Configuration management
│   └── models.py                 # Pydantic data models
├── pyproject.toml
└── LICENSE
```

## Technical Details

| Component | Technology |
|-----------|------------|
| Embedding model | [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) (384 dimensions) |
| Vector search | Cosine similarity via NumPy dot product |
| Cache format | Python pickle with file locking |
| MCP framework | [FastMCP](https://github.com/jlowin/fastmcp) |
| Package manager | [uv](https://docs.astral.sh/uv/) |

## License

[MIT License](LICENSE)