Loading
Loading docs…
Was this page helpful?
We're open source. If actrone-memory has been useful to you, a star on GitHub means a lot to us.
Star the projectLoading docs…
Configuration for the open-source memory library. Python (actrone-memory) reads ACTRONE_-prefixed environment variables; TypeScript (actrone-memory) is configured in code via MemoryManager.create({ config }).
Note
ACTRONE_-prefixed environment variables (and a .env file) when a MemoryConfig is created, or takes one you build in code, and its config includes the backend choice, Redis/Qdrant URLs, and embedding provider. TypeScript has no environment auto-loading: behaviour is tuned via the config option on MemoryManager.create() (camelCase keys), while stores and embeddings are supplied as l1 / l2 / embedder adapters rather than config fields.Both languages default to the same thing: an in-process InMemoryStore for L1 and L2, and a local embedder, MemoryManager.create() needs zero arguments to work. Nothing below is required; it's all opt-in tuning.
| Setting | Python default | TypeScript default |
|---|---|---|
| Backend | in-memory (redis_qdrant opt-in) | in-memory (RedisL1Store/QdrantL2Store opt-in) |
| Embedding provider | local (ONNX → sentence-transformers → hashing) | local (fastembed bge-small → hashing) |
| Relevance threshold | calibrated per embedder | calibrated per embedder |
| Token counting | heuristic, ~4 chars per token | heuristic, ~4 chars per token |
| Max episodic memories (L2) | 500 | 10 |
| Max session turns (L1) | 50 | 50 |
| Session TTL | 24h (Redis backend only) | not applicable: no built-in TTL |
| Hybrid retrieval (RRF) | on | on |
| Reranking | off | off (needs a Reranker passed in) |
| Auto-summarisation | on, after 20 turns | not implemented in TypeScript |
| Fact extraction | off (OpenAI-gated) | off |
Similarity scores are not comparable across embedding models, so each built-in embedder carries the threshold it was calibrated for, measured on a labelled set of relevant and unrelated pairs: 0.63 for bge-small-en-v1.5, 0.4 for MiniLM (Python's [local] extra), and 0.3 for the keyword-only hashing embedder. An embedder that declares none, such as OpenAI or your own, uses 0.72 in Python and 0.7 in TypeScript. Set the threshold yourself only when you have measured it for your model; relevance_threshold / mm.relevanceThreshold shows the value in use.
Tip
maxEpisodicMemoriesin particular defaults differently, and auto-summarisation is a Python-only feature today. Set values explicitly if you need parity between a Python and a TypeScript service on the same product.# Backend: "memory" (default, zero services) or "redis_qdrant" (production)
ACTRONE_BACKEND=memory
# Store connections, only read when ACTRONE_BACKEND=redis_qdrant
ACTRONE_REDIS_URL=redis://localhost:6379
ACTRONE_QDRANT_URL=http://localhost:6333
ACTRONE_QDRANT_API_KEY= # if using Qdrant Cloud
ACTRONE_QDRANT_COLLECTION=agent_memories
ACTRONE_QDRANT_TIMEOUT=10.0
# Redis connection pool
ACTRONE_REDIS_MAX_CONNECTIONS=10
ACTRONE_REDIS_SOCKET_TIMEOUT=5.0
ACTRONE_REDIS_SOCKET_CONNECT_TIMEOUT=5.0
# Embeddings: provider defaults to "local" (no key needed); "openai" or "hashing" also valid
ACTRONE_EMBEDDING_PROVIDER=local
ACTRONE_OPENAI_API_KEY=sk-... # only required when EMBEDDING_PROVIDER=openai
ACTRONE_EMBEDDING_MODEL=text-embedding-3-small
ACTRONE_EMBEDDING_DIMENSIONS=1536
ACTRONE_HASHING_DIMENSIONS=256 # vector width when the hashing embedder is used
ACTRONE_EMBEDDING_CACHE_TTL_SECONDS=604800 # 7 days
# Session (L1)
ACTRONE_SESSION_TTL_HOURS=24
ACTRONE_MAX_SESSION_TURNS=50
# Episodic memory (L2)
ACTRONE_MAX_EPISODIC_MEMORIES=500
# ACTRONE_RELEVANCE_THRESHOLD= # unset: the embedder's calibrated value (0.63 bge-small, 0.4 MiniLM, 0.3 hashing, 0.72 OpenAI)
ACTRONE_RELEVANCE_WEIGHT=0.7 # recency_weight = 1 - relevance_weight
ACTRONE_RECENCY_WEIGHT=0.3
ACTRONE_HYBRID_RETRIEVAL=true # dense + BM25 + recency via Reciprocal Rank Fusion
# Reranking: opt-in, needs the [onnx] extra
ACTRONE_RERANK_ENABLED=false
ACTRONE_RERANK_TOP_K=20
# Fact extraction: opt-in, needs an OpenAI-configured embedder/summariser
ACTRONE_EXTRACT_FACTS=false
# Summarisation
ACTRONE_AUTO_SUMMARISE=true
ACTRONE_SUMMARISE_AFTER_TURNS=20
ACTRONE_SUMMARISATION_MODEL=gpt-4o-mini
ACTRONE_SUMMARISE_COOLDOWN_SECONDS=300
# Token counting: "heuristic" (default, ~4 chars per token, no network) or "tiktoken" (exact; needs the [tiktoken] extra)
ACTRONE_TOKEN_COUNTER=heuristic
# Token budget fractions must sum to 1.0
ACTRONE_BUDGET_FRACTION_SYSTEM=0.30
ACTRONE_BUDGET_FRACTION_EPISODIC=0.25
ACTRONE_BUDGET_FRACTION_SESSION=0.35
ACTRONE_BUDGET_FRACTION_CURRENT_TURN=0.10from actrone_memory import MemoryManager
from actrone_memory.config import MemoryConfig
config = MemoryConfig(
backend="redis_qdrant",
redis_url="redis://localhost:6379",
qdrant_url="http://localhost:6333",
embedding_provider="openai",
openai_api_key="sk-...",
session_ttl_hours=48,
max_session_turns=100,
)
memory = await MemoryManager.create(config=config)In TypeScript, pass a partial config to MemoryManager.create(). All keys have safe defaults, so you only set what you need. Every field is camelCase:
import { MemoryManager } from "actrone-memory"
const memory = await MemoryManager.create({
config: {
maxSessionTurns: 100, // cap retained turns per session (L1), default 50
maxEpisodicMemories: 500, // L2 candidates before budget pruning, default 10
budgetFractionSession: 0.35, // share of the token budget for recent turns
budgetFractionEpisodic: 0.25, // share for long-term memories
hybridRetrieval: true, // dense + BM25 + recency via Reciprocal Rank Fusion, default true
rerankTopK: 20, // rerank window when a reranker is supplied
},
})
// relevanceThreshold is calibrated per embedder; set it only for an embedder you have measured.Tip
create() rather than silently producing a manager that never recalls anything, so a typo fails fast.Tip
l1 / l2 / embedder options instead. That is also how you plug in a store you wrote yourself, since the built-in adapters use the same seam. See Architecture overview for the production wiring.