AgentRecall

Persistent two-tier memory for AI agents. Battle-tested across 134 sessions with 10 agent roles.

Short-term (markdown files, always loaded) + Long-term (SQLite + OpenAI embeddings, searched on-demand).

Install

pip install agentrecall-memory

Zero required dependencies. SQLite is Python stdlib.

Optional semantic search:

pip install agentrecall-memory[embeddings]
export OPENAI_API_KEY="sk-..."

Quick Start

CLI

# Initialize
agentrecall init

# Store a memory (auto-dedup via cosine similarity >0.92)
agentrecall store coder gotchas "kamal app exec spawns new container, use docker exec"
agentrecall store social exhausted_stories "blue-green deploy order loss" --tags deploy,sqlite

# Search (semantic + keyword fallback)
agentrecall search coder gotchas "kamal file not found"

# List categories
agentrecall list coder

# Check health
agentrecall check --all

Python API

from agentrecall import MemoryStore, MemorySearch

# Store
store = MemoryStore()
store.store("coder", "gotchas", "kamal spawns new container", tags=["kamal", "docker"])

# Search
search = MemorySearch()
results = search.search("coder", "gotchas", "kamal file not found")
for text in results:
    print(text)

# List categories
categories = store.list_categories("coder")

How It Works

Two-Tier Design

Semantic Dedup

Every store call embeds the text via OpenAI text-embedding-3-small and checks cosine similarity against all existing entries in the same role/category. Similarity > 0.92 blocks the store (raises DuplicateError).

Without an API key, falls back to exact text matching.

Search

1. Embed the query
2. Compute cosine similarity against all entries with embeddings
3. Return entries above threshold (0.75), sorted by similarity
4. If no embedding matches: keyword fallback (>=50% keyword match)
5. No API key: keyword-only search

Graceful Degradation

Works fully offline without an OpenAI API key:

• Store: exact text dedup (case-insensitive)
• Search: keyword matching (>=50% of query words must appear)

Agent Skills

Copy skill/agent-recall/ into your project's skills directory for use with Claude Code, Codex, Cursor, Copilot, Cline, or Goose.

cp -r skill/agent-recall/ .claude/skills/agent-recall/

Configuration

Environment variables:

CLI Reference

agentrecall store <role> <category> "text" [--tags t1,t2] [--db path]
agentrecall search <role> <category> "query" [--db path]
agentrecall list <role> [--db path]
agentrecall check [--fix] [--long-term] [--all] [--dir path] [--db path]
agentrecall init [--dir path]
agentrecall migrate [--dry-run] [--rebuild] [--dir path] [--db path]

Exit codes: 0 = success/found, 1 = not-found/validation-fail, 2 = input error.

Migration from JSONL

If you have existing JSONL memory files:

agentrecall migrate --dir /path/to/memory/
agentrecall migrate --rebuild  # Re-embed entries missing embeddings

License

MIT