pip install shaheen-dbShaheen DB (named after the Royal Falcon) is a lightweight, zero-ops, self-consolidating cognitive memory layer designed specifically for AI Agents.
Instead of treating agent memory as a massive, unstructured dumping ground of raw vector embeddings—which leads to bloated context windows, duplicate facts, high token costs, and retrieval noise—Shaheen DB implements an opinionated, biologically inspired cognitive memory pipeline.
Most AI agents use standard vector databases (like Pinecone or Chroma) for memory. This approach has three fatal flaws in production:
- Semantic Noise: If a user mentions eating a croissant on Day 1, and asks about their business strategy on Day 30, a standard vector search will often retrieve the croissant log due to query overlaps. This pollutes the LLM's prompt.
- Context Bloat: Raw transcripts contain filler words, greetings, and temporary statements. Feeding these directly to LLMs burns tokens and incurs high latency.
- No Fact Evolution: If a user says "My name is Saif" on Day 1, and "Actually, write my name as Saif Al-Islam" on Day 5, a vector search will return both statements, forcing the LLM to guess which name is correct.
Shaheen DB solves this by separating sensory ingestion from long-term factual consolidation, and automatically forgetting trivial logs over time.
[ Agent Conversations / Logs ]
│
▼ (Immediate Ingestion < 5ms)
┌────────────────────────┐
│ Sensory Buffer (SQL) │ ◄─── Instant Vector Match
└───────────┬────────────┘
│
▼ (Background "Sleep" Loop)
┌──────────────────────────┐
│ Consolidation Engine │
└──────┬────────────┬──────┘
│ │
(Extract facts) │ │ (Extract relationships)
▼ ▼
┌──────────┐ ┌───────────┐
│ Vectors │ │ Knowledge │
│ Index │ │ Graph │
└──────────┘ └───────────┘
- Sensory Store (Short-term Memory): Immediate, high-throughput writes (under 5ms) to an SQLite buffer running in Write-Ahead Logging (WAL) mode. Vectorized immediately for real-time semantic retrieval.
- Consolidation Loop (The "Sleep" Cycle): An asynchronous process that processes raw logs using structured LLM outputs to extract structured entities (nodes) and relationships (edges).
-
Cognitive Decay (Forgetting): Applies mathematical exponential decay (
$decay = e^{-\lambda \Delta t}$ ) to temporary sensory logs. Trivial information decays and is deleted, while pinned/permanent facts and organized graph connections are preserved permanently. -
Hybrid GraphRAG Retrieval: A unified retrieval query that automatically builds a context pack containing:
- Recent Conversations: Highly relevant active sensory logs.
- Associated Entities & Facts: Consolidated entities matching the query.
- Associative Relationships: Sub-graphs of connections between matching entities.
- Zero-Ops GraphRAG: Get the reasoning benefits of a Knowledge Graph and Vector Database in a single local SQLite file. No Neo4j servers, no Docker, no external cloud configurations.
- Biologically Inspired Sleep Cycle: Runs LLM extraction in the background to convert unstructured dialogue into structured relationships.
- Native Memory Decay: Automatic time-based cleanup of trivial logs to keep context window sizes minimal and token costs low.
- Microsecond Graph Traversals: Uses optimized SQL queries inside SQLite to fetch 1-hop and 2-hop entity neighborhoods in microseconds.
- Dependency-Optional Offline Mode: Support for local CPU/GPU embedding generation via
sentence-transformersor local API calls to Ollama to avoid heavy PyTorch dependencies.
Install the package requirements:
pip install -r requirements.txtfrom shaheen import Shaheen
# Initialize Shaheen DB (creates a local SQLite file)
db = Shaheen(db_path="memory.db")
# 1. Store sensory memories (fast write, immediate indexing)
db.remember("User: Hello! My name is Saif. I am a software engineer.")
db.remember("User: I am building Shaheen DB in Python to solve agent memory.")
db.remember("User: By the way, I have a pet falcon named Swift.", permanent=True) # Pinned context!
# 2. Trigger the "Sleep" cycle to organize memory into a graph
db.consolidate()
# 3. Recall coordinated memory (returns a unified GraphRAG context)
result = db.recall("Who is Saif and what is his pet?")
print(result["context_text"])The generated context pack is cleanly formatted, ready to be injected straight into your LLM prompt template:
### Recent Conversations & Logs:
- [2026-05-20 08:31:13] User: By the way, I have a pet falcon named Swift. [Permanent] (decay relevance: 1.00, query match: 0.85)
### Relevant Entities & Facts:
- saif (Person): role: software engineer (query match: 0.88)
- swift (Animal): type: falcon, owner: saif (query match: 0.84)
- shaheen-db (Software): purpose: AI agent memory, creator: saif (query match: 0.75)
### Associative Relationships:
- saif --[BUILDING]--> shaheen-db (status: active)
- saif --[OWNER_OF]--> swiftBecause the "Sleep Cycle" (db.consolidate()) calls generative LLMs to extract information, it takes a few seconds to complete. You should never run it inline on the main thread during active user conversations, as it will slow down your agent's response time.
Instead, use one of the following production patterns:
Automatically trigger consolidation in a background thread when the count of raw, unconsolidated memories reaches a threshold (e.g., every 15 conversation turns).
import threading
def handle_incoming_message(text: str):
# 1. Ingest immediately (takes < 5ms)
db.remember(f"User: {text}")
# 2. Trigger consolidation in the background if the threshold is met
unconsolidated_count = len(db.db.get_unconsolidated_memories())
if unconconsolidated_count >= 15:
threading.Thread(target=db.consolidate, daemon=True).start()
# 3. Retrieve context & query agent LLM
context = db.recall(text)
return agent.respond(text, context)Trigger consolidation only when the user has stopped talking to the agent for a set duration (e.g., 10 minutes of inactivity).
import time
import threading
last_activity = time.time()
has_slept = False
def idle_watcher():
global last_activity, has_slept
while True:
time.sleep(30)
if time.time() - last_activity > 600 and not has_slept:
db.consolidate()
has_slept = True
# Start idle watcher thread on startup
threading.Thread(target=idle_watcher, daemon=True).start()For multi-user SaaS setups, run a nightly script (e.g., at 2:00 AM) that iterates through all active user databases and triggers .consolidate().
# Run daily at 2:00 AM
0 2 * * * python /app/scripts/trigger_nightly_consolidation.pyNote
Base URL is Optional: Standard OpenAI, Google Gemini, Anthropic, and local Ollama setups are auto-configured by default. You do not need to set SHAHEEN_LLM_BASE_URL unless you are using a third-party gateway like OpenRouter or Groq.
| Provider | SHAHEEN_LLM_PROVIDER |
Native SDK | Embedding Source | Notes |
|---|---|---|---|---|
| OpenAI | openai |
✅ | OpenAI API | Default provider |
| Google Gemini | gemini |
✅ | Gemini API | Uses google-genai SDK |
| Anthropic Claude | anthropic |
✅ | SentenceTransformers (local) | Anthropic has no embedding API |
| Ollama (local) | openai |
Via base URL | Ollama API | Point base URL to localhost:11434 |
| Groq | openai |
Via base URL | Groq API | Ultra-fast inference |
| OpenRouter | openai |
Via base URL | OpenRouter API | Access to 200+ models |
| DeepSeek | openai |
Via base URL | DeepSeek API | Cost-effective cloud inference |
| LM Studio | openai |
Via base URL | LM Studio API | Local GUI-based model runner |
| SentenceTransformers | local |
✅ | Python (in-process) | 100% offline, no API needed |
Shaheen DB is highly flexible and supports 100% cloud, hybrid, and 100% offline stacks. Configure it using these environment variables:
export SHAHEEN_LLM_PROVIDER="gemini"
export GEMINI_API_KEY="your-gemini-api-key"
# Defaults used automatically:
# SHAHEEN_LLM_MODEL="gemini-2.5-flash"
# SHAHEEN_EMBEDDING_MODEL="text-embedding-004"export SHAHEEN_LLM_PROVIDER="openai"
export SHAHEEN_LLM_API_KEY="your-openai-key"
# Defaults used automatically:
# SHAHEEN_LLM_MODEL="gpt-4o-mini"
# SHAHEEN_EMBEDDING_MODEL="text-embedding-3-small"Uses the native Claude SDK with Tool Use to guarantee structured JSON extraction during the sleep cycle. Since Anthropic has no embedding API, vector search runs locally via SentenceTransformers.
export SHAHEEN_LLM_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="your-anthropic-key"
# Defaults used automatically:
# SHAHEEN_LLM_MODEL="claude-3-5-sonnet-20241022"
# SHAHEEN_EMBEDDING_MODEL="all-MiniLM-L6-v2" (runs locally, no API cost)Point Shaheen DB at any OpenAI-compatible provider to access hundreds of models with a single API key.
export SHAHEEN_LLM_PROVIDER="openai"
# OpenRouter (access to 200+ models including Claude, Llama, Mistral, Gemini)
export SHAHEEN_LLM_BASE_URL="https://openrouter.ai/api/v1"
export SHAHEEN_LLM_API_KEY="your-openrouter-key"
export SHAHEEN_LLM_MODEL="meta-llama/llama-3-70b-instruct" # or any model slug
# Groq (ultra-fast Llama / Mixtral inference)
# export SHAHEEN_LLM_BASE_URL="https://api.groq.com/openai/v1"
# export SHAHEEN_LLM_API_KEY="your-groq-key"
# export SHAHEEN_LLM_MODEL="llama3-70b-8192"Runs vector search 100% locally on your CPU (saving API costs), and only queries OpenRouter's cloud for the background consolidation sleep cycle.
export SHAHEEN_LLM_PROVIDER="local" # Runs SentenceTransformers locally
export SHAHEEN_LLM_BASE_URL="https://openrouter.ai/api/v1"
export SHAHEEN_LLM_API_KEY="your-openrouter-key"
export SHAHEEN_LLM_MODEL="deepseek/deepseek-chat"Runs both embeddings and the LLM locally via Ollama. Keeps your Python environment lightweight (does NOT require PyTorch or sentence-transformers).
export SHAHEEN_LLM_PROVIDER="openai"
export SHAHEEN_LLM_BASE_URL="http://localhost:11434/v1" # Required to redirect the API client to Ollama
export SHAHEEN_LLM_API_KEY="ollama" # Dummy key
export SHAHEEN_LLM_MODEL="llama3"
export SHAHEEN_EMBEDDING_MODEL="nomic-embed-text"
export SHAHEEN_EMBEDDING_DIM="768"Uses native SentenceTransformers locally on your CPU for vector search, and calls Ollama for the LLM consolidation sleep cycle.
export SHAHEEN_LLM_PROVIDER="local" # Runs SentenceTransformers locally (no base URL needed for embeddings)
# Points the LLM client to Ollama (Defaults to http://localhost:11434/v1 automatically)
export SHAHEEN_LLM_MODEL="llama3"
export SHAHEEN_LLM_API_KEY="ollama" # Dummy key- ACID Transactions: The Knowledge Graph (entities/edges) and vector embeddings reside in the same SQLite database. All consolidation updates happen in single database transactions. If an LLM extraction fails or gets interrupted, the database rolls back cleanly.
- WAL Mode Concurrency: Configured with SQLite Write-Ahead Logging. Your AI agent can stream messages and write sensory logs on the main thread, while the consolidation loop runs on a background scheduler without locking the database.
- Lazy Loading: Offline embedding dependencies (
sentence-transformers) are only loaded if you explicitly setSHAHEEN_LLM_PROVIDER="local". If you use cloud APIs or Ollama, your application starts instantly without PyTorch memory overhead.
Shaheen DB is open-source software licensed under the MIT License.