Skip to content

We're open source. If actrone-memory has been useful to you, a star on GitHub means a lot to us.

Memory configuration

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 }).

Python vs TypeScript configuration

Note

Python reads 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.

Defaults: Python vs TypeScript

SettingPython defaultTypeScript default
Backendin-memory (redis_qdrant opt-in)in-memory (RedisL1Store/QdrantL2Store opt-in)
Embedding providerlocal (ONNX → sentence-transformers → hashing)local (fastembed bge-small → hashing)
Relevance thresholdcalibrated per embeddercalibrated per embedder
Token countingheuristic, ~4 chars per tokenheuristic, ~4 chars per token
Max episodic memories (L2)50010
Max session turns (L1)5050
Session TTL24h (Redis backend only)not applicable: no built-in TTL
Hybrid retrieval (RRF)onon
Rerankingoffoff (needs a Reranker passed in)
Auto-summarisationon, after 20 turnsnot implemented in TypeScript
Fact extractionoff (OpenAI-gated)off
Redaction on readoff (no classes)off (no classes)

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

The two libraries share a design, not identical numbers. 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.

Environment variables

.env
# 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

# Redaction on read: the sensitivity classes masked in every read, as a JSON list
ACTRONE_REDACT_SENSITIVITIES=[]         # e.g. ["pii", "sensitive"]

# 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.10

Programmatic configuration (Python)

python
from 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,
    redact_sensitivities=["pii", "sensitive"],  # mask these tags in every read
)
memory = await MemoryManager.create(config=config)

Programmatic configuration (TypeScript)

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:

typescript
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
    redactSensitivities: ["pii", "sensitive"], // mask these tags in every read, default []
  },
})
// relevanceThreshold is calibrated per embedder; set it only for an embedder you have measured.

Tip

Out-of-range values are rejected at create() rather than silently producing a manager that never recalls anything, so a typo fails fast.

Tip

Stores and the embedder are not config fields in TypeScript: pass them as the 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.
Was this page helpful?