lite-recall 1.0.0

ReCALL Lite: a lightweight persistent memory layer for LLM applications

ReCALL Lite — A Lightweight Memory Engine for LLMs

A persistent, human-like memory layer for LLM applications. Store facts across sessions, retrieve by meaning, summarize old memories, and forget what no longer matters.

Installation

pip install lite-recall

Optional extras:

pip install "lite-recall[vector]"   # FAISS acceleration
pip install "lite-recall[groq]"     # Groq LLM connector
pip install "lite-recall[openai]"   # OpenAI connector
pip install "lite-recall[transformers]"  # Local HF models

Quick Start

from lite_recall import LiteAgent, ReCALLConfig, ReCALLLite
from lite_recall.connectors import GroqConnector

config = ReCALLConfig(
    backend="sqlite",
    db_path="memory.db",
    user_id="alice",
    thread_id="personal",
)
model = GroqConnector(api_key="gsk_...", model_name="llama-3.1-8b-instant")
memory = ReCALLLite(config=config, summarizer_model=model)
agent = LiteAgent(memory, model)

agent.process("My name is Alice and I love Italian food.")
reply = agent.process("What is my name and what do I like?")
print(reply)  # "Your name is Alice and you love Italian cuisine..."
memory.save()

Core Concepts

Memory Engine (ReCALLLite)

The core memory system stores facts as graph nodes with semantic embeddings. Related nodes are linked by similarity, old nodes are auto-summarized, and low-importance nodes are pruned.

from lite_recall import ReCALLConfig, ReCALLLite

memory = ReCALLLite(ReCALLConfig(backend="sqlite", user_id="bob"))

memory.create_node("Bob works as a data scientist.")
memory.create_node("Bob has a cat named Whiskers.")

print(memory.query("What does Bob do?"))
# "Bob works as a data scientist."

print(memory.get_stats())
# {"node_count": 2, "edge_count": 0, ...}

memory.save()

Agent (LiteAgent)

The agent bridges memory and an LLM. It automatically stores user statements (non-questions) as memory and retrieves relevant context for each response.

from lite_recall import LiteAgent, ReCALLConfig, ReCALLLite
from lite_recall.connectors import GeminiAPIConnector

model = GeminiAPIConnector(api_key="...", model_version="gemini-2.5-flash")
memory = ReCALLLite(ReCALLConfig(user_id="charlie"))
agent = LiteAgent(memory, model)

agent.process("I enjoy hiking on weekends.")
reply = agent.process("What do I enjoy doing?")
# Recalls "hiking" from stored memory

Configuration

All Options

from lite_recall import ReCALLConfig

config = ReCALLConfig(
    # Persistence
    backend="sqlite",          # "sqlite" (default), "parquet"
    db_path="recall_lite.db",  # database file path
    user_id="alice",           # isolates memory per user
    thread_id="personal",       # isolates memory per thread
    enable_faiss=False,         # enable FAISS vector index

    # Memory behavior
    sim_threshold=0.35,        # similarity threshold for linking
    merge_threshold=0.80,      # similarity threshold for merging
    max_nodes=1500,            # max nodes before forgetting
    summary_batch_size=10,     # nodes per auto-summary

    # Retrieval weights
    query_summary_weight=0.6,  # summary node influence
    query_raw_weight=0.4,      # raw memory node influence

    # Smart forgetting
    enable_smart_forgetting=True,
    importance_protection_threshold=1.8,

    # Embedding
    embedding_model="all-distilroberta-v1",
    log_level="INFO",
)

From Environment Variables

config = ReCALLConfig.from_env()
# Reads RECALL_DB_PATH, RECALL_USER_ID, RECALL_THREAD_ID, etc.

From Dictionary

config = ReCALLConfig.from_dict({"backend": "sqlite", "user_id": "alice"})

Connectors

Every connector follows the same ModelConnector interface:

class ModelConnector(ABC):
    def generate(self, prompt: str, max_new_tokens: int) -> str: ...

Groq

from lite_recall.connectors import GroqConnector

model = GroqConnector(api_key="gsk_...", model_name="llama-3.1-8b-instant")
# pip install groq

Gemini

from lite_recall.connectors import GeminiAPIConnector

model = GeminiAPIConnector(api_key="AIza...", model_version="gemini-2.5-flash")

OpenAI

from lite_recall.connectors import OpenAIConnector

model = OpenAIConnector(api_key="sk-...", model_name="gpt-4")
# pip install openai

HuggingFace

from lite_recall.connectors import HuggingFaceConnector

model = HuggingFaceConnector(model_name="google/gemma-2b-it")
# pip install transformers

Ollama

from lite_recall.connectors import OllamaConnector

model = OllamaConnector(model_name="llama3")

Backends

SQLite (default)

Persists memory with user/thread isolation to a single .db file.

ReCALLConfig(backend="sqlite", db_path="recall_lite.db", user_id="alice")

FAISS (vector search)

Faster retrieval for large memory graphs.

ReCALLConfig(backend="sqlite", enable_faiss=True)
# pip install "lite-recall[vector]"

Parquet (legacy)

File-based persistence using parquet format.

ReCALLConfig(backend="parquet", memory_prefix="my_memory")

User/Thread Isolation

Each user and thread gets fully isolated memory — no data leakage between them.

alice = ReCALLLite(ReCALLConfig(user_id="alice", thread_id="personal"))
bob = ReCALLLite(ReCALLConfig(user_id="bob", thread_id="personal"))

alice.create_node("I am from Chennai.")
bob.create_node("I am from Mumbai.")

print(alice.query("Where am I from?"))  # Chennai
print(bob.query("Where am I from?"))    # Mumbai

Smart Forgetting

Frequently accessed and summary-linked nodes are protected. Low-value, stale nodes are pruned when max_nodes is exceeded.

config = ReCALLConfig(
    enable_smart_forgetting=True,
    importance_protection_threshold=2.0,
    max_nodes=100,
)
memory = ReCALLLite(config=config)

Auto-Summarization

When enough unsummarized memory nodes accumulate (configurable by summary_batch_size), the engine creates a summary node using the LLM. Summary nodes receive higher retrieval weight.

config = ReCALLConfig(summary_batch_size=10)
memory = ReCALLLite(config=config, summarizer_model=model)

Monitoring

stats = memory.get_stats()
# {
#   "node_count": 42,
#   "edge_count": 12,
#   "summary_count": 3,
#   "memory_health_score": 78.5,
#   "backend": "sqlite",
#   "faiss_enabled": false,
#   "smart_forgetting_enabled": true,
#   "user_id": "alice",
#   "average_importance": 1.4,
#   "protected_nodes": 5,
#   "forgotten_this_cycle": 2,
#   ...
# }

Save and Load

memory.save()     # persist to backend
memory.load()     # restore from backend

By default, memory auto-loads from the backend on construction.

CLI Demo

python -m lite_recall
# or
python lite_main.py

Loads .env and starts an interactive chat with persistent memory.

ReCALL Lite vs RAG / GraphRAG

Requirement	RAG	GraphRAG	ReCALL Lite
Incremental learning	No (re-index)	No (rebuild)	Yes (per node)
Forgetting stale facts	No	No	Yes (smart forgetting)
Auto-summarization	No	Yes (batch)	Yes (incremental)
Cross-session persistence	No	No	Yes
Relationship linking	No	Yes (typed)	Yes (semantic)
Importance-aware retrieval	No	No	Yes
User/thread isolation	Manual	Manual	Built-in
LLM cost per interaction	Low	Very high	Low

Use ReCALL Lite when you are building an AI agent, companion, or assistant that needs to remember facts about a user across sessions, learn incrementally, and retain what matters.

License

Apache 2.0. See LICENSE.

Built by Project Genesis — an autonomous AI research engine.