Python SDK

Search & Retrieval

Ask in natural language, get memories back ranked by what fits the task — and, when you need it, the full story of why.

Search

search_memories runs a ranked, natural-language search over the scope of the call:

hits = client.search_memories("who owns pricing?", top_k=5)

for hit in hits:
    print(hit.id, hit.text)
    print(hit.created_at)        # ISO-8601 string, or None
    print(hit.source_agent_id)   # who wrote it (in shared namespaces)
    hit.raw                      # everything the server sent

It returns a plain list[SearchResult] — this route answers with a bare JSON array, and the SDK does not invent a wrapper around it.

Searching is not free of side effects

Each search strengthens the memories it returns — they become more likely to surface again — and is recorded in your query log. That is by design: retrieval is rehearsal, like human memory. If you need to probe rankings without moving them, use search_explain(..., rehearse=False) — see Inspection.

List recent memories

list_memories returns the newest memories first, no query needed:

rows = client.list_memories(top_k=20)

# Memories consolidated away over time are hidden by default:
archive = client.list_memories(include_archived=True)

Litica consolidates memory in the background — older, superseded memories can be archived. include_archived=True is the explicit window into that archive.

Trace one memory

get_memory_trace answers “why did this come up?” for a single memory: what it is about, how salient it is, every query that ever retrieved it, and the memories it links to:

trace = client.get_memory_trace(1042)

trace.salience           # how important Litica currently ranks it
trace.retrieval_count    # how many times it has been retrieved
trace.retrievals         # every query that pulled it up, with rank + score
trace.linked_memories    # related memories it connects to

Note: rank inside retrievals is 0-based here, but 1-based in search_explain. The SDK mirrors both exactly as the server sends them rather than quietly renumbering.

The query log

Every search is logged. list_queries reads that log, newest first:

for q in client.list_queries(limit=50):
    print(q.created_at, q.agent_id, q.query_text, q.result_count)

Who has memories here?

client.list_agents()   # ["default", "support-bot", "research-bot"]
client.get_tenant()    # the tenant id this API key resolves to

Next steps

Namespaces — search across memory that several agents share.
Inspection — the full score breakdown behind a ranking.