Text Volt

Minimal CLI text vault with hierarchical memory management to prevent AI agent rot.

Built by @milonspace

Text Volt is a production-grade command-line tool for storing and searching text using Google Gemini embeddings. It implements a three-tier memory system (working/warm/cold) to prevent memory overload and maintain agent performance over time.

✨ Features

• 🔍 Semantic Search - Vector-based similarity search using cosine similarity
• 💾 Smart Caching - Automatic embedding cache prevents redundant API calls
• 🚫 Duplicate Prevention - SHA256 hash-based deduplication ensures unique entries
• 🧠 Hierarchical Memory - Three-tier memory system (working/warm/cold) prevents agent rot
• 🔄 Auto Consolidation - Automatic tier migration based on access patterns
• 🔐 Secure Config - Environment-based API key management
• ⚡ Minimal CLI - Clean, intuitive interface with short aliases (a, s, l, d)
• 📥 Stdin Support - Pipe text directly into the vault

🚀 Quick Start

Installation

# Install with UV
uv sync

# Or use UVX to run from anywhere
uvx textvolt --help

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Add your Gemini API key:

# Edit .env and add your API key
GEMINI_API_KEY=your_api_key_here

Usage

# Add text
textvolt a "Your text here"

# Search semantically
textvolt s "query"

# List entries
textvolt l

# Delete entry
textvolt d 1

📖 Commands

Command	Alias	Description
add	a	Add text to vault
search	s	Semantic search
list	l	List entries
delete	d, rm	Delete entry
consolidate	-	Consolidate memory tiers
validate	-	Validate memory integrity
reset	-	Reset vault (with confirmation)

Options

• -q, --quiet - Quiet mode (minimal output, useful for scripting)
• -n, --limit <N> - Limit number of results (default: 5 for search, 10 for list)
• -t, --tier <tier> - Filter by memory tier (working/warm/cold)
• -m, --meta <json> - Add JSON metadata to entry

💡 Examples

Basic Workflow

# Add multiple entries
textvolt a "Project idea: Build a CLI tool"
textvolt a "Meeting notes: Discussed API design"
textvolt a "Code snippet: Fast vector search"

# Search for related content
textvolt s "API"                    # Finds API-related entries
textvolt s "code" -n 3              # Top 3 code-related entries

# List recent entries
textvolt l                          # Last 10 entries
textvolt l -n 20                    # Last 20 entries
textvolt l -t working               # Only working memory

# Clean up
textvolt d 5                        # Delete entry #5
textvolt consolidate                # Optimize memory tiers

Piping Text

# From file
cat notes.txt | textvolt add

# From command output
git log --oneline -5 | textvolt add

# Quiet mode for scripting
echo "text" | textvolt add -q

Using UVX (from anywhere)

uvx textvolt add "Your text here"
uvx textvolt s "query"
uvx textvolt l

🏗️ Architecture

┌─────────────────────────────────────────┐
│      CLI Interface (Minimal TUI)        │
│  Commands: a/s/l/d + stdin support      │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│      Memory Manager (Hierarchical)      │
│  ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│  │ Working  │ │   Warm   │ │  Cold   │ │
│  │ (Recent) │ │ (Active) │ │(Archive)│ │
│  └──────────┘ └──────────┘ └─────────┘ │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    Vector Store (SQLite + numpy)        │
│  - Embeddings storage (JSON)            │
│  - Hash-based deduplication            │
│  - Semantic search (cosine)             │
│  - Metadata tracking                    │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│   Gemini Embedding Service              │
│   - Text-based caching                  │
│   - Secure API key management           │
│   - Error handling & retries            │
└─────────────────────────────────────────┘

🛡️ Preventing AI Agent Rot

Text Volt implements several strategies to prevent agent degradation:

1. Hierarchical Memory - Three-tier system prevents memory overload
2. Automatic Consolidation - Moves entries between tiers based on access patterns
3. Access Tracking - Tracks access counts and timestamps for relevance
4. Memory Validation - Integrity checks detect corruption
5. Stateless Operations - Idempotent operations reduce state-related errors
6. Size Limits - Configurable limits for each memory tier
7. Duplicate Prevention - Hash-based deduplication prevents redundant entries
8. Embedding Cache - Reuses embeddings for duplicate text, saving API calls

⚙️ Configuration

All configuration is done through environment variables in .env:

Variable	Description	Default
GEMINI_API_KEY	Your Google Gemini API key (required)	-
TEXTVOLT_VAULT_PATH	Path to SQLite database	~/.textvolt/vault.db
TEXTVOLT_WORKING_SIZE	Maximum entries in working memory	100
TEXTVOLT_WARM_SIZE	Maximum entries in warm memory	1000
TEXTVOLT_EMBEDDING_MODEL	Embedding model name	gemini-embedding-exp-03-07

See .env.example for a template.

📁 Project Structure

textvolt/
├── pyproject.toml          # UV project configuration
├── .env.example            # Environment template
├── textvolt/
│   ├── __init__.py
│   ├── config.py          # Settings & configuration
│   ├── embedding.py       # Gemini embedding service
│   ├── vault.py           # Vector storage & search
│   ├── memory.py          # Memory management
│   └── cli.py             # CLI interface
└── README.md              # This file

🎯 Design Decisions

1. SQLite over PostgreSQL - Minimal dependency, portable, sufficient for CLI tool
2. JSON storage for embeddings - Simple, no additional vector extensions needed
3. Cosine similarity - Standard vector similarity metric, implemented in pure NumPy
4. Hierarchical memory - Three-tier system prevents memory overload and agent rot
5. Stateless design - Each operation is independent, reducing state-related errors
6. Hash-based deduplication - SHA256 hashing for fast duplicate detection
7. Text-based caching - Automatic embedding cache reduces API costs
8. Minimal CLI - Clean, intuitive interface with short aliases for zero friction
9. UV/UVX - Fast, modern Python package management and execution

🔒 Security

• API keys stored in .env file (never committed to git)
• No hardcoded credentials in source code
• Environment-based configuration for all sensitive data
• SHA256 hashing for duplicate detection (no plaintext comparison)

⚡ Performance

• Caching - Duplicate text uses cached embeddings (no API call)
• Deduplication - Hash-based lookup is O(1) for duplicate detection
• Search - Cosine similarity with NumPy (efficient for <10K entries)
• Memory - Automatic consolidation prevents database bloat

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

🎨 Design Principles

This project follows YAGNI, KISS, and DRY principles for maintainable architecture.