Metadata-Version: 2.4
Name: lite-recall
Version: 1.0.0
Summary: ReCALL Lite: a lightweight persistent memory layer for LLM applications
Author: Project Genesis
License-Expression: Apache-2.0
Keywords: llm,memory,retrieval,agent,embeddings,knowledge-graph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sentence-transformers<6,>=5.0
Requires-Dist: networkx>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Requires-Dist: pyarrow>=12.0
Requires-Dist: loguru>=0.7.0
Provides-Extra: vector
Requires-Dist: faiss-cpu; extra == "vector"
Provides-Extra: openai
Requires-Dist: openai; extra == "openai"
Provides-Extra: transformers
Requires-Dist: transformers; extra == "transformers"
Provides-Extra: groq
Requires-Dist: groq; extra == "groq"
Dynamic: license-file

# 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

```bash
pip install lite-recall
```

Optional extras:

```bash
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

```python
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.

```python
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.

```python
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

```python
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

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

### From Dictionary

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

## Connectors

Every connector follows the same `ModelConnector` interface:

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

### Groq

```python
from lite_recall.connectors import GroqConnector

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

### Gemini

```python
from lite_recall.connectors import GeminiAPIConnector

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

### OpenAI

```python
from lite_recall.connectors import OpenAIConnector

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

### HuggingFace

```python
from lite_recall.connectors import HuggingFaceConnector

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

### Ollama

```python
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.

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

### FAISS (vector search)

Faster retrieval for large memory graphs.

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

### Parquet (legacy)

File-based persistence using parquet format.

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

## User/Thread Isolation

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

```python
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.

```python
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.

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

## Monitoring

```python
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

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

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

## CLI Demo

```bash
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.
