arandu
Long-term memory system for AI agents. Extract facts from conversations, resolve entities, reconcile updates, and retrieve relevant context — works with any LLM provider.
Quickstart
pip install arandu[openai]
import asyncio
from arandu import MemoryClient
from arandu.providers.openai import OpenAIProvider
provider = OpenAIProvider(api_key="sk-...")
memory = MemoryClient(
database_url="postgresql+psycopg://user:pass@localhost/mydb",
llm=provider,
embeddings=provider,
)
async def main():
await memory.initialize() # creates tables (idempotent)
# Write — extracts facts automatically
result = await memory.write(user_id="user_123", message="I live in São Paulo with my wife Ana")
print(result.facts_added) # [{"fact_text": "Lives in São Paulo", ...}]
# Retrieve — semantic search + keyword + LLM reranking
context = await memory.retrieve(user_id="user_123", query="where does the user live?")
print(context.context) # "## Known facts about the user:\n- Lives in São Paulo ..."
asyncio.run(main())
Requirements
- Python 3.11+
- PostgreSQL with pgvector extension
- An LLM provider (OpenAI included, or implement your own)
Custom Providers
Implement the LLMProvider and EmbeddingProvider protocols to use any backend:
from arandu.protocols import LLMProvider, EmbeddingProvider
class MyProvider:
async def complete(self, messages, temperature=0, response_format=None, max_tokens=None) -> str:
... # your LLM call
async def embed(self, texts: list[str]) -> list[list[float]]:
... # your embedding call
async def embed_one(self, text: str) -> list[float] | None:
... # single text embedding
Configuration
from arandu import MemoryConfig
config = MemoryConfig(
topk_facts=20, # max facts to retrieve
min_similarity=0.20, # cosine similarity threshold
min_confidence=0.55, # minimum fact confidence
enable_reranker=True, # LLM reranking of results
recency_half_life_days=14, # exponential decay half-life
)
memory = MemoryClient(database_url="...", llm=provider, embeddings=provider, config=config)
Architecture
The SDK implements a 4-stage write pipeline and a 3-signal read pipeline:
Write: Message → Extract (LLM) → Entity Resolution (exact/fuzzy/LLM) → Reconcile (ADD/UPDATE/NOOP/DELETE) → Upsert
Read: Query → Semantic Search (pgvector) + Keyword Search (ILIKE) + Recency Scoring → LLM Rerank → Context Formatting
Documentation
For comprehensive documentation including conceptual guides, configuration reference, and cookbook examples:
https://pe-menezes.github.io/arandu/
Contributing
Contributions are welcome! Please read the Contributing Guide before submitting a pull request.
License
1 maintainer
Release files for arandu 0.14.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| arandu-0.14.3.tar.gz | 714.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| arandu-0.14.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 852.5 kB
Release files / arandu-0.14.3.tar.gz
| Download URL | arandu-0.14.3.tar.gz |
|---|---|
| Size | 714.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
606a98e007518088496a95362c77e5a77e94d237ffcb6003ccff2709ebdc3047
|
|
BLAKE2b-256 checksum How to use checksums |
994d53c58443870b203a19b8b1f6880b631d17aa8d3a2ccb3192b1cc5832651c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 16, 2026.
Transparency logRelease files / arandu-0.14.3-py3-none-any.whl
| Download URL | arandu-0.14.3-py3-none-any.whl |
|---|---|
| Size | 137.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
138fe59f5e28f1e5d92cca033e7876c57e56a89a3fc91704be7bf3990cdefe7f
|
|
BLAKE2b-256 checksum How to use checksums |
d649ea06d195b4246f834587e4a9cc3844e1e3630914b17cf6cfa543009ec4bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 16, 2026.
Transparency log
