Two-tier memory architecture
Actrone uses a two-tier memory system: a hot L1 tier for fast recent-turn access, and a semantic L2 tier for long-term recall. Both are fetched in parallel on every turn. In-memory by default, Redis (L1) and Qdrant (L2) are an opt-in production backend, not a requirement to start.
Full API reference
Tip
actrone-memory reference and the TypeScript actrone-memory reference.Two languages, one model
The open-source memory library ships for both ecosystems and they are kept in lock-step: actrone-memory, published under that one name on PyPI for Python and on npm for TypeScript/JavaScript. Same two-tier architecture, same 4-phase retrieval, same result shapes. Only the surface idioms differ.
Note
snake_case in Python (max_session_turns) and camelCase in TypeScript (maxSessionTurns). Result fields follow the same convention (recent_turns / recentTurns). Both libraries run with zero services by default (an in-memory store and a local embedder), so you can start without Redis, Qdrant, or an API key in either language.Why two tiers?
Flat vector search over all memories is slow and expensive. Flat recent-turn storage has no semantic recall. Two tiers keep recent turns a single read away and search only long-term memories by meaning, combined in one parallel fetch with budget-aware pruning.
On the Python library's bundled benchmark, with the in-memory store and the keyword embedder, a whole retrieval takes 0.27 ms at the median and 1.43 ms at p95, from one run on a development machine. Run python -m actrone_memory.benchmark to measure your own; with Redis and Qdrant, add your network round trips.
For the design behind it, from where recent turns live to how the token budget is split, read How actrone-memory’s two-tier memory works on the blog.
Backends: in-memory by default, Redis, Postgres, Qdrant, pgvector, or your own
Both libraries ship an InMemoryStore that backs L1 and L2 with zero external services. This is what MemoryManager.create() uses with no arguments, in Python and TypeScript alike. It's process-local and doesn't survive a restart, which is fine for local development or a single-process app but not for production.
For production, pick the stores you already run. Redis (or any Redis-protocol server such as Valkey) and Postgres back the hot tier; Qdrant and Postgres + pgvector back the semantic tier. In Python, the Redis + Qdrant pair has an env shortcut: install the redis/qdrant/production extras and set ACTRONE_BACKEND=redis_qdrant. Otherwise pass the stores to MemoryManager.create() in either language. Every method call is identical whichever you choose: swapping backends never touches your application code.
Nothing about those adapters is privileged. L1Store and L2Store are small interfaces (a typing.Protocol in Python), so a store you write yourself plugs into the same seam, and the library ships a conformance suite so you can prove it behaves like the built-in ones. See Configuration.
L1: hot memory (Redis in production)
Recent turns are capped at max_session_turns (default 50). On the Redis backend they're stored as a Redis List with TTL session_ttl_hours (default 24h, Python only, the TypeScript core has no built-in session TTL); on the in-memory backend they live in a process-local map. Reading the recent turns from Redis is a single range read.
Note
L2: semantic memory (Qdrant in production)
L2 holds long-term memories: facts you inject with inject_memory / injectMemory, session summaries (Python), and facts the opt-in extractor distils. Recent turns stay in L1. Each memory is embedded, by default with a local embedder (a local ONNX model when the [onnx] extra or the fastembed package is installed, otherwise a dependency-free hashing embedder that matches shared keywords, see Configuration), or OpenAI's text-embedding-3-small if you opt in, and indexed for semantic search. By default, results are ranked by Reciprocal Rank Fusion across dense (vector) and lexical (BM25) search plus recency (see Retrieval pipeline for the exact formula and the classic weighted-blend fallback). Only entries above the relevance threshold are returned; each embedder carries the threshold it was calibrated for (0.63 for bge-small, 0.3 for hashing).
Budget allocation
The 4-phase retrieval pipeline splits the token budget you pass in by fixed fractions:
- Session turns (L1 recent): 35%
- Episodic (L2 semantic results): 25%
- The rest (40%) is left for your system prompt and the current turn. Python names that share explicitly (system 30%, current turn 10%) and checks that all four add up to 1.
Each share is filled in priority order and pruned to fit; an unused share is not handed to the other. Retrieval never touches the part reserved for your system prompt.
Auto-summarisation
In Python, after summarise_after_turns turns (default 20), a background task compresses the session and writes the summary back into L2 (Qdrant in production, in-memory by default). The summary is written by gpt-4o-mini when the OpenAI provider is configured, and is otherwise an extractive summary taken from the conversation itself, so no data leaves your machine by default. The raw turns are retained. A per-session cooldown (default 300s) prevents concurrent re-summarisation. The TypeScript library does not summarise automatically.
Fact extraction (opt-in)
Beyond raw turns and summaries, extract_memories / extractMemories reads a session’s recent turns for durable facts. It stores each one as its own L2 entry (content_type="fact" / contentType: "fact", source="extracted"), tagged with a sensitivity. It’s off by default in both languages because every extraction is a model call.
The extractor works with any OpenAI-compatible chat API, so the model can run on your own machine. Point it at a local server such as Ollama, vLLM or LM Studio, and the conversation never leaves that machine. The examples below use Ollama with qwen2.5:3b. Install the OpenAI client first:
pip install "actrone-memory[openai]" # Python
npm install openai # TypeScriptIn Python, memory_with_local_extraction builds a manager whose extractor calls the local server, and learn_from_session turns a session’s turns into stored facts:
from actrone_memory import MemoryManager, OpenAIFactExtractor
async def memory_with_local_extraction(
base_url: str = "http://localhost:11434/v1",
) -> MemoryManager:
"""Extract facts with a model on any OpenAI-compatible server."""
extractor = OpenAIFactExtractor(
base_url=base_url,
api_key="ollama", # Ollama ignores the key; the client needs one
model="qwen2.5:3b",
)
return await MemoryManager.create(extractor=extractor)
async def learn_from_session(
memory: MemoryManager, agent_id: str, session_id: str
) -> list[str]:
"""Turn the session's recent turns into stored facts."""
return await memory.extract_memories(agent_id, session_id)The TypeScript version passes an openai client pointed at the same server:
import { MemoryManager, OpenAIFactExtractor } from 'actrone-memory'
import OpenAI from 'openai'
/** Extract facts with a model on any OpenAI-compatible server. */
export async function memoryWithLocalExtraction(
baseURL = 'http://localhost:11434/v1',
): Promise<MemoryManager> {
// Ollama ignores the key; the client needs one
const client = new OpenAI({ baseURL, apiKey: 'ollama' })
const extractor = new OpenAIFactExtractor(client, 'qwen2.5:3b')
return MemoryManager.create({ extractor })
}
/** Turn the session's recent turns into stored facts. */
export async function learnFromSession(
memory: MemoryManager,
agentId: string,
sessionId: string,
): Promise<string[]> {
return memory.extractMemories(agentId, sessionId)
}To extract with OpenAI itself, build the extractor without the base URL, the placeholder key and the model: it then reads OPENAI_API_KEY and uses its default model. In Python you can also set extract_facts=True with the OpenAI embedding provider, and the library builds that extractor for you.
Note
qwen2.5:3b found 14 of 14 expected facts but tagged preferences and feelings as none. Check the tags before you rely on them to redact anything.Provenance, sensitivity, and right-to-erasure
Every stored memory carries two governance fields alongside its content, a source recording where it came from (TypeScript types this as a canonical set: "user", "assistant", "tool", "summary", "injected", "extracted", "reflection", "imported", "unknown", or a namespaced string like "tool:web_search"; Python leaves it a free-form string, defaulting to "unknown") and a sensitivity classification ("none" → "low" → "pii" → "sensitive") for filtering, redaction on read and retention policy. Both default to the least-sensitive value for memories written before this was tracked, and are set automatically by extract_memories' LLM classifier, or explicitly when you call inject_memory / injectMemory directly.
This is also what backs local right-to-erasure: erase_agent_memories / eraseAgentMemories irreversibly deletes an agent's L2 store (and, if you pass a session_id, that session's L1 turns too). It's a hard local delete in the OSS library, the seed the hosted platform graduates into cryptographically provable erasure.
# Python
await memory.erase_agent_memories(agent_id="support-bot", session_id="s1")// TypeScript
await memory.eraseAgentMemories("support-bot", "s1")Privacy and PII: what the library does and does not do
Warning
store_turn / storeTurn is written to L1/L2 exactly as given, in plain text (or as a plain vector embedding). Read this section before you store real user conversations.What it does have is redaction on read, by sensitivity tag. A memory whose tag you redact comes back with its content replaced by [redacted: pii], or whichever class it carries. Its embedding is dropped too, so it stays out of the prompt you build. The stored memory doesn’t change. Pass the classes for one call:
# Python
ctx = await memory.retrieve_context(
agent_id, session_id, query, 4096, redact=["pii", "sensitive"]
)// TypeScript
const ctx = await memory.retrieveContext(agentId, sessionId, query, 4096, {
redact: ["pii", "sensitive"],
})To redact on every read, set redact_sensitivities / redactSensitivities (see Configuration). Passing an empty list turns it off for one call. It covers retrieve_context / retrieveContext and search_memories / searchMemories, and so every framework adapter built on them.
Redaction is only as good as the tags, so know where they come from:
- Raw turns and auto-generated summaries are not scanned for PII and always default to
sensitivity="none", whether or not they contain personal data, so redaction never masks them. - The one place classification happens automatically is the opt-in
extract_memories/extractMemoriesfact extractor (off by default, LLM-gated): its extracted facts get a realsensitivityvalue from the classifier prompt. - Outside of that,
sensitivityis only ever accurate if you set it explicitly oninject_memory/injectMemory. - There is no field-level or at-rest encryption in the library itself. Encrypting data in Redis/Qdrant (or your in-memory process) is an infrastructure concern you own, the same as any other datastore you self-host.
If you’re storing real conversations, the practical pattern is:
- Scrub sensitive fields before calling
store_turn, since turns are never masked. - Turn on fact extraction if you want distilled facts tagged automatically, or set the tag yourself on
inject_memory. - Turn on redaction on read, so tagged facts stay out of your prompts.
- Use
erase_agent_memories(above) to fulfil a right-to-erasure request.
Automatic PII detection, tokenisation before a model sees the text, and policy-driven retention are planned for the hosted platform, which has not launched.