Metadata-Version: 2.4
Name: recallos-sdk
Version: 0.1.0
Summary: Python SDK for RecallOS -- persistent memory infrastructure for AI agents.
Author: Raitul Hasan
License-Expression: MIT
Project-URL: Homepage, https://github.com/recallos/recallos
Project-URL: Repository, https://github.com/recallos/recallos
Keywords: memory,ai-agents,llm,rag,vector-search,agentic-ai,recallos
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31

# RecallOS Python SDK (`recallos-sdk`)

[![PyPI version](https://img.shields.io/pypi/v/recallos-sdk.svg)](https://pypi.org/project/recallos-sdk/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/recallos-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Persistent memory infrastructure for production AI agents.**

RecallOS gives your AI agents persistent, self-updating memory: it extracts durable facts from conversations, stores them with confidence/importance scores, and retrieves them with hybrid vector + keyword ranking to construct token-budgeted context blocks.

---

## Installation

```bash
pip install recallos-sdk
```

---

## Quickstart

```python
from recallos_sdk import MemoryClient

# Connect to local RecallOS or remote instance
memory = MemoryClient(base_url="http://localhost:8420")
# Or with API key:
# memory = MemoryClient(base_url="https://your-domain.com", api_key="rk_live_...")

# 1. Remember facts from conversation
result = memory.remember(
    user_id="user_123",
    text="I prefer dark mode and concise responses with Python examples."
)
print("Created memories:", len(result.created))

# 2. Recall token-budgeted context block
ctx = memory.context(
    user_id="user_123",
    query="How should I format my response?",
    max_tokens=400
)
print("Context for LLM prompt:\n", ctx.context)

# 3. Provide usefulness feedback (adaptive learning)
if ctx.included_memory_ids:
    memory.feedback(memory_id=ctx.included_memory_ids[0], useful=True)
```

---

## Key Features

- **Automatic Fact Extraction**: Extracts durable user facts, preferences, entities, and temporal updates.
- **Hybrid Retrieval**: Combines semantic vector similarity, BM25 keyword matching, recency decay, and usefulness scoring.
- **Token-Budgeted Context**: Automatically fits the most relevant memories into your prompt token window.
- **Adaptive Memory**: Reinforces frequently useful memories and decays stale information over time.
- **Zero Cloud Lock-in**: Works out of the box with local SQLite + local Ollama models.

---

## License

MIT License. See `LICENSE` for details.
