Skip to content

Using it

Start with private memory and no authorization setup. Add an adapter and explicit grants when an agent needs shared memory.

Retold is distributed through GitHub Releases while its PyPI trusted publisher is being configured. Python 3.12 or 3.13 is required.

python -m pip install "retold[local-models] @ https://github.com/adimyth/retold/releases/download/v1.2.1/retold-1.2.1-py3-none-any.whl"

The quick start uses Retold's lite profile: the 87 MB MiniLM embedder and a 552 MB NLI evidence model. Allow time for the one-time download on the first write. With both models cached, the first write in a new process took 3.7 seconds on the development Apple Silicon Mac, the following search took 8 ms, and a repeated cached search took 1 ms.[^4]

Save this as quickstart.py and run python quickstart.py:

from retold import Retold

with Retold.open("memory.sqlite", profile="lite") as retold:
    with retold.session(user_id="aditya") as memory:
        memory.remember(
            "I prefer concise answers.",
            evidence="I prefer concise answers.",
            attribute="answer_style",
        )
        result = memory.search("What kind of answers do I prefer?")
        print(result.text)

The result includes the stored claim and the reason it passed retrieval:

Recalled 1 memory for "What kind of answers do I prefer?".

[01a08...] semantic · confirmed · user_statement · event 2026-09-10 · scope agent:assistant/aditya
I prefer concise answers.
matched: dense 0.53 (rank 1), lexical 2/3 (rank 1); fused rank 1; passed dense 0.53 ≥ 0.32 (semantic)

The executable version lives at examples/quickstart.py. It needs no API key. memory.remember records the supplied quote as a trusted user turn and sends the claim through the same evidence, lifecycle, indexing, and retrieval policies used by the framework adapters.

attribute="answer_style" identifies the current fact that this memory describes. A later statement with the same attribute reinforces or supersedes this record according to its evidence, time, and source authority. When you omit attribute, Retold derives a content-specific private key. That is convenient for standalone memories, but rephrased or contradicting claims are not guaranteed to resolve to the same current fact. Use an explicit attribute for preferences and other facts that can change.

The quote has to support the claim. "Aditya prefers concise answers." backed by "I prefer concise answers." is fine, because Retold knows who is speaking. A claim the quote does not support raises UnsupportedEvidenceError instead of being stored as a guess that expires in thirty days. Pass allow_inference=True when a tentative record is what you want.

See Retold decide

The local quick start proves storage and explained recall. The utility-aware example exercises the decision that distinguishes Retold: use a stored preference when it changes an answer, and skip retrieval when the answer needs no private context.

# From a source checkout
python examples/utility_aware_quickstart.py

question: Give me a code example that reads a JSON file.
decision: regenerated
memory used: 1
answer: Here is a Python example, using your saved preference.

question: What is dependency injection?
decision: baseline_no_gaps
memory used: 0
answer: Dependency injection supplies dependencies from outside an object.

examples/utility_aware_quickstart.py uses real MiniLM retrieval with deterministic planner and admission policies, so it runs without an API key and produces the same decisions on every run. A production host supplies model-backed policies and evaluates that bundle in shadow mode before serving it.

Add Retold to an agent

The adapters register the memory tools, derive identity from trusted run configuration, capture turns, and schedule transcript extraction when the host ends a session.

Deep Agents

python -m pip install "retold[local-models,live,deepagents] @ https://github.com/adimyth/retold/releases/download/v1.2.1/retold-1.2.1-py3-none-any.whl"
export ANTHROPIC_API_KEY="your-key"

examples/deepagents_live.py contains a complete Anthropic integration. Download it or run python examples/deepagents_live.py from a source checkout. examples/deepagents_demo.py uses scripted model replies and fake memory models when you want to inspect adapter behavior without keys or model downloads.

CrewAI

python -m pip install "retold[local-models,live,crewai] @ https://github.com/adimyth/retold/releases/download/v1.2.1/retold-1.2.1-py3-none-any.whl"
export ANTHROPIC_API_KEY="your-key"

examples/crewai_live.py contains the complete integration. Download it or run python examples/crewai_live.py from a source checkout. examples/crewai_demo.py is the deterministic simulation.

Both live examples grant one agent access to the user's shared scope. The framework-neutral quick start needs no grant because it writes to the implicit private scope for that agent and user.

OpenAI

python -m pip install "retold[local-models,live,crewai] @ https://github.com/adimyth/retold/releases/download/v1.2.1/retold-1.2.1-py3-none-any.whl"
export OPENAI_API_KEY="your-key"
# From a source checkout
python examples/openai_live.py

examples/openai_live.py is a complete CrewAI integration using OpenAI for the agent, background extraction, and candidate review. Embeddings, retrieval, and evidence checks remain local. Retold also exposes provider-neutral completion, planner, admission, embedding, and evidence protocols for applications that supply another provider.