Metadata-Version: 2.4
Name: totalrecall-cli
Version: 0.1.0
Summary: TotalRecall CLI — Memory Infrastructure for AI Agents (Python)
Author-email: TotalRecall <hello@totalrecall.dev>
License: MIT
Project-URL: Homepage, https://totalrecall.dev
Project-URL: Documentation, https://totalrecall.dev/docs
Project-URL: Repository, https://github.com/tope-olajide/total-recall
Project-URL: Issues, https://github.com/tope-olajide/total-recall/issues
Keywords: ai,memory,llm,qwen,cli,semantic-search,embeddings
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: totalrecall-sdk>=0.1.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# TotalRecall CLI (Python)

> **Memory Infrastructure for AI Agents** — Manage persistent memory directly from your terminal.

[![PyPI version](https://img.shields.io/pypi/v/totalrecall-cli.svg)](https://pypi.org/project/totalrecall-cli)
[![Python Version](https://img.shields.io/pypi/pyversions/totalrecall-cli.svg)](https://pypi.org/project/totalrecall-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The TotalRecall CLI gives you full control over your AI agent's memory — from your terminal, CI/CD pipelines, and inside AI agent loops. Add, search, update, delete, and manage memories with **25+ commands** across 8 capability areas.

```bash
pip install totalrecall-cli
```

---

## 📦 Installation

### Global (recommended)

```bash
pip install totalrecall-cli

# Now you can use `totalrecall` or `tr` (shorthand alias) from anywhere
totalrecall --help
tr --help
```

### Local in a virtual environment

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install totalrecall-cli
```

---

## 🚀 Quick Start

```bash
# Step 1: Initialize with your API key and project ID
totalrecall init --api-key tr_your_key --project-id proj_123

# Step 2: Check your connection
totalrecall status

# Step 3: Add a memory
totalrecall add "User prefers dark mode and Vim editor" --category preference --importance 0.8

# Step 4: Search your memories
totalrecall search "What editor does the user prefer?"

# Step 5: Pin important memories (never forgotten)
totalrecall pin mem_abc123
```

---

## 📖 Command Reference

### 🔧 Setup

| Command | Description |
|---------|-------------|
| `totalrecall init` | Interactive setup wizard for API key, project ID, and base URL |
| `totalrecall status` | Verify API connection, view project overview, quality score, and usage |
| `totalrecall config` | Manage local configuration (get, set, show) |
| `totalrecall entity project list` | List all projects |
| `totalrecall entity project create <name>` | Create a new project |
| `totalrecall entity project get <id>` | Get project details |
| `totalrecall entity project usage` | Get project usage and plan limits |
| `totalrecall entity agent-set <id>` | Set the current agent ID in local config |

### 🧠 Memory Management

| Command | Description |
|---------|-------------|
| `totalrecall add [content]` | Add a memory from text, file, or stdin — with PII redaction & approval modes |
| `totalrecall list` | List memories with filters (category, state, temporal status, speaker, subject) |
| `totalrecall get <id>` | Get a memory by ID with optional version history (`--versions`) |
| `totalrecall search <query>` | Semantic search across all memories by meaning — with `--context` for LLM injection |
| `totalrecall update <id>` | Update memory content, category, importance, or label |
| `totalrecall delete <id>` | Delete a memory (requires `--yes` or `--force` confirmation) |

### 🔄 AI Operations

| Command | Description |
|---------|-------------|
| `totalrecall forget` | Run intelligent forgetting — preview with `--dry-run` or execute |
| `totalrecall import <file>` | Bulk import memories from a JSON file |
| `totalrecall export` | Export all memories to stdout or a file (`--output`) |
| `totalrecall graph` | Export the knowledge graph as JSON or CSV |

### 📂 Multimodal Ingestion

| Command | Description |
|---------|-------------|
| `totalrecall ingest text <file>` | Ingest text files (.txt, .md, .json, .csv, .log, .xml, .yaml, .yml) |
| `totalrecall ingest image <file>` | Ingest images via Qwen VL description (.png, .jpg, .webp, .gif, .bmp, .svg) |
| `totalrecall ingest audio <file>` | Ingest audio via Qwen ASR + speaker diarization (.mp3, .wav, .ogg, .flac, .m4a, .aac) |
| `totalrecall ingest video <file>` | Ingest video via Qwen VL frame analysis (.mp4, .webm, .mov, .avi, .mkv) |
| `totalrecall ingest batch <files...>` | Batch ingest multiple files at once |

### 🛡️ Governance

| Command | Description |
|---------|-------------|
| `totalrecall pin <id>` | Pin a memory to prevent forgetting/archiving |
| `totalrecall unpin <id>` | Unpin a memory to allow natural lifecycle management |
| `totalrecall pinned` | List all pinned memories |

### 🌐 Webhooks & API Keys

| Command | Description |
|---------|-------------|
| `totalrecall webhook list` | List all webhooks |
| `totalrecall webhook create <url>` | Create a webhook |
| `totalrecall webhook delete <id>` | Delete a webhook |
| `totalrecall webhook test <id>` | Test a webhook |
| `totalrecall api-key list` | List all API keys |
| `totalrecall api-key create <name>` | Create a new API key |
| `totalrecall api-key revoke <id>` | Revoke an API key |

### 👥 Team Management

| Command | Description |
|---------|-------------|
| `totalrecall team list` | List team members |
| `totalrecall team invite <email>` | Invite a team member |
| `totalrecall team remove <id>` | Remove a team member |
| `totalrecall team transfer <id>` | Transfer project ownership |

### 📋 Events

| Command | Description |
|---------|-------------|
| `totalrecall event list` | List recent lifecycle events |
| `totalrecall event get <id>` | Get details of a specific event |

---

## 🧪 Examples

### Setup

```bash
# Interactive setup
totalrecall init

# Quick setup with flags
totalrecall init --api-key tr_abc123 --project-id proj_456

# Use custom API endpoint
totalrecall init \
  --api-key tr_abc123 \
  --project-id proj_456 \
  --base-url https://my-totalrecall-instance.com

# Check status
totalrecall status
```

### Adding Memories

```bash
# From inline text
totalrecall add "The user's name is Alice" --category fact --importance 0.9

# From a file
totalrecall add --file notes.md --category preference

# From stdin
echo "User prefers VS Code" | totalrecall add --stdin --category preference

# Pin on creation
totalrecall add "Critical business rule" --category fact --pin

# With PII redaction
totalrecall add "My email is alice@example.com" --redact basic

# Detect conflicts before writing
totalrecall add "User prefers light mode" --detect-conflicts
```

### Semantic Search

```bash
# Basic search
totalrecall search "What are the user's preferences?"

# Search with filters
totalrecall search "coding preferences" --category preference --limit 5 --threshold 0.8

# Get formatted context for LLM injection
totalrecall search "Tell me about the user" --context
```

### Memory Management

```bash
# List all memories
totalrecall list

# List with filters
totalrecall list --category preference --limit 20 --state active

# Get a specific memory with version history
totalrecall get mem_abc123 --versions

# Update a memory
totalrecall update mem_abc123 --content "Updated content" --importance 0.95

# Delete with auto-confirm
totalrecall delete mem_abc123 --force
```

### Forgetting Cycle

```bash
# Preview without making changes
totalrecall forget --dry-run

# Execute forgetting
totalrecall forget
```

### Import / Export

```bash
# Export all memories to a file
totalrecall export --output my-memories.json

# Export with archived memories
totalrecall export --output all-memories.json --include-archived

# Import memories from a JSON file
totalrecall import my-memories.json
```

### Multimodal Ingestion

```bash
# Ingest a text file
totalrecall ingest text report.md

# Analyze an image
totalrecall ingest image screenshot.png

# Transcribe and extract memories from audio
totalrecall ingest audio meeting.mp3 --title "Team Standup" --speaker-count 4

# Analyze a video
totalrecall ingest video demo.mp4

# Batch ingest multiple files
totalrecall ingest batch notes.md document.pdf screenshot.png
```

### Governance

```bash
# Pin an important memory
totalrecall pin mem_abc123

# Unpin a memory
totalrecall unpin mem_abc123

# List all pinned memories
totalrecall pinned
```

### Webhooks & API Keys

```bash
# List webhooks
totalrecall webhook list

# Create a webhook
totalrecall webhook create https://hooks.example.com/event "memory.created,memory.updated"

# List API keys
totalrecall api-key list

# Create an API key
totalrecall api-key create "my-app-key"
```

### Team Management

```bash
# List team members
totalrecall team list

# Invite a member
totalrecall team invite alice@example.com --role editor

# Transfer ownership
totalrecall team transfer user_abc123
```

---

## 🤖 Agent Mode

The CLI has a dedicated **agent mode** that outputs clean, structured JSON for AI agents to consume programmatically.

### Usage

```bash
# Enable agent mode with --agent flag
totalrecall --agent search "user preferences"

# Or use the shorter --json flag
totalrecall --json status

# Combine with agent identity for memory attribution
totalrecall --agent --agent-id my-agent-1 --session-id sess_abc123 add "User likes Python"
```

### JSON Response Envelope

All agent mode responses follow a consistent structure:

```json
{
  "status": "success",
  "command": "search",
  "duration_ms": 134,
  "scope": {
    "project_id": "proj_123",
    "agent_id": "my-agent-1",
    "session_id": "sess_abc123"
  },
  "count": 2,
  "data": [
    {
      "id": "mem_abc",
      "content": "User prefers dark mode",
      "score": 0.95
    }
  ]
}
```

### Error Response

```json
{
  "status": "error",
  "command": "delete",
  "duration_ms": 45,
  "error": {
    "code": "NOT_FOUND",
    "message": "Memory not found"
  }
}
```

### Using in AI Agent Loops

```python
import subprocess
import json

def search_memories(query: str) -> list:
    """Search memories and return structured results for an AI agent."""
    result = subprocess.run(
        ["totalrecall", "--agent", "search", query],
        capture_output=True, text=True
    )
    response = json.loads(result.stdout)

    if response["status"] == "success":
        return response["data"]
    raise RuntimeError(response["error"]["message"])
```

### Global Flags

| Flag | Alias | Description |
|------|-------|-------------|
| `--agent` | | Agent mode — JSON envelope for AI agents |
| `--json` | | JSON output mode — raw JSON data without envelope |
| `--quiet` | | Suppress all human-readable output |
| `--verbose` | | Show detailed debug output |
| `--agent-id` | | Agent identity for memory attribution |
| `--session-id` | | Session ID for grouping memories |
| `--api-key` | | Override API key (also: `TR_API_KEY` env var) |
| `--project-id` | | Override project ID (also: `TR_PROJECT_ID` env var) |
| `--base-url` | | Override API base URL (also: `TR_BASE_URL` env var) |
| `--yes` | `-y` | Auto-confirm destructive operations |
| `--no-color` | | Disable ANSI color codes |
| `--help` | `-h` | Show help |
| `--version` | `-v` | Show version |

---

## 🔒 PII Redaction

The CLI can redact PII from memory content before storage:

| Level | Description | Redacted Patterns |
|-------|-------------|-------------------|
| `off` | No redaction | — |
| `basic` | API keys, emails, tokens | API keys, emails, Slack tokens, GitHub tokens, JWTs |
| `full` | Everything | Basic + phone numbers, SSN, credit cards, IP addresses, AWS keys |

### Examples

```bash
# Full redaction (default)
totalrecall add "My email is alice@example.com" --redact full

# Basic redaction
totalrecall add "Key: sk-abc123def456" --redact basic

# No redaction (raw storage)
totalrecall add --redact off "Secret info"
```

---

## ✅ Memory Governance

### Pinned Memories

Pin critical memories to prevent the forgetting cycle from archiving or deleting them:

```bash
# Pin an important memory
totalrecall pin mem_abc123

# Pin on creation
totalrecall add "Critical business rule" --pin

# Unpin when no longer critical
totalrecall unpin mem_abc123

# List all pinned
totalrecall pinned
```

### Write Approval Modes

| Mode | Behavior |
|------|----------|
| `auto` | Write immediately (default) |
| `confirm` | Warns before writing |
| `review` | Creates memory with label for manual review |

---

## 🐍 CI/CD Usage

The CLI works perfectly in CI/CD pipelines:

```bash
# GitHub Actions example
- name: Backup memories
  run: |
    totalrecall export --output backup.json
  env:
    TR_API_KEY: ${{ secrets.TR_API_KEY }}
    TR_PROJECT_ID: ${{ secrets.TR_PROJECT_ID }}
```

---

## 🔧 Configuration

The CLI stores configuration locally in `~/.totalrecall/config.json`.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `TR_API_KEY` | API key (overrides config file) |
| `TR_PROJECT_ID` | Project ID (overrides config file) |
| `TR_BASE_URL` | API base URL (overrides config file) |
| `TR_AGENT_ID` | Default agent ID for memory attribution |

### Commands

```bash
# Show all config
totalrecall config show

# Get a specific value
totalrecall config get api-key

# Set a value
totalrecall config set project-id proj_new

# Override via flags (any command)
totalrecall --api-key tr_new --project-id proj_new status
```

---

## 🧪 Development

```bash
# Clone and install
git clone https://github.com/tope-olajide/total-recall.git
cd totalrecall

# Install the CLI in development mode
cd packages/cli-python
pip install -e ".[dev]"

# Run tests
pytest

# Test locally
totalrecall --help

# Build for PyPI
python -m build
```

---

## 📝 License

MIT © 2026 TotalRecall
