🗃️ stash

External memory for AI agents - a lightweight RLM (Recursive Language Model) that any Clawdbot can use.

Store persistent key-value data, load large files into searchable contexts, and manage agent memory - all without consuming precious tokens.

Features

• Key-value storage - stash set/get for persistent data
• Context loading - Load large files without eating tokens
• Fast search - Full-text search with FTS5, plus regex
• Chunking - Split large contexts into manageable pieces
• Memory helpers - Quick remember/recall for agent notes
• Zero dependencies - Pure Python, just sqlite3 (built-in)
• Portable - Single SQLite database, easy to sync/backup

Installation

pip install stash-rlm

Or install from source:

git clone https://github.com/klodshannon/stash.git
cd stash
pip install -e .

Quick Start

# Store things persistently
stash set api:openai "sk-12345..."
stash get api:openai

# Load large files into context (doesn't eat tokens!)
stash load server.log --as logs
stash peek logs 0:50              # View lines 0-50
stash search "ERROR" --in logs    # Search within context

# Quick memory for agent notes
stash remember "Hunter prefers concise answers" --tag prefs
stash recall prefs
stash recall                      # List all memories

# Manage entries
stash list
stash stats
stash forget logs

Commands

Key-Value Storage

stash set <key> <value>     # Store a value
stash set config - < file   # Store from stdin
stash get <key>             # Retrieve a value
stash get <key> --json      # Output as JSON

Context Management

stash load <file> [--as <id>]    # Load file into context
stash peek <id> [range]          # View slice (e.g., "10:20")
stash peek <id> 100 -n           # 20 lines from 100, numbered
stash search <pattern> --in <id> # Search within context
stash search <pattern>           # Search all entries

Memory Helpers

stash remember "note" [--tag <tag>]  # Store a memory
stash recall [tag]                   # Recall memories

Management

stash list [--type <type>]    # List entries
stash stats                   # Storage statistics
stash forget <key>            # Delete entry
stash version                 # Show version
stash export -o backup.json   # Export to JSON
stash import backup.json      # Import from JSON
stash ctx-list                # List contexts
stash ctx-info <id>           # Context details
stash ctx-rm <id>             # Remove context

Use Cases

For Clawdbots / AI Agents

# Store frequently needed data
stash set user:tz "America/Chicago"
stash set user:name "Hunter"

# Load documentation for reference
stash load ~/project/README.md --as docs
stash search "API" --in docs

# Remember things between sessions
stash remember "Project uses FastAPI, not Flask"
stash remember "Deploy target is Railway" --tag deploy

Context Window Management

# Load a huge log file
stash load production.log --as prod

# Search instead of loading entire file
stash search "OutOfMemory" --in prod

# Peek at relevant sections
stash peek prod 1000:1050

Knowledge Base

# Build up knowledge over time
stash remember "User prefers dark mode" --tag ui
stash remember "Always use TypeScript" --tag code
stash remember "Meetings are Tue/Thu 10am" --tag schedule

# Recall by topic
stash recall code
stash recall schedule

Storage

Data is stored in a SQLite database at:

• Linux/macOS: ~/.local/share/stash/stash.db
• Or set STASH_HOME environment variable
• Or use --db <path> flag

The database is fully portable - copy it to sync between machines.

Comparison with Aleph

stash is for simple, persistent storage. Aleph is for complex analysis sessions.

License

MIT - Built by Klod at Shannon Labs.