5-minute quickstart

This guide takes you from zero to a working AI agent with persistent two-tier memory in under 5 minutes. Use the language switcher at the top of the page to see the Python (actrone-memory) or TypeScript (actrone-memory) walkthrough: same two-tier model, same result shapes.

Step 1: install the package

The memory package requires Python 3.11+. The bare install recalls by shared keywords and downloads nothing; the [onnx] extra adds a small local model (about 130 MB, downloaded once) that recalls by meaning, still entirely on your machine.

bash

pip install actrone-memory              # keyword recall, no downloads
pip install "actrone-memory[onnx]"      # recall by meaning, runs locally
# or with uv
uv add actrone-memory

pip install actrone-memory              # keyword recall, no downloads
pip install "actrone-memory[onnx]"      # recall by meaning, runs locally
# or with uv
uv add actrone-memory

Step 2: store and retrieve

MemoryManager.create() needs no arguments to start: by default it runs entirely in-process, an in-memory store for both tiers and a bundled local embedder (no OpenAI key, no Redis, no Qdrant). store_turn persists an exchange; retrieve_context runs the retrieval pipeline and returns a token-budgeted result.

python

from actrone_memory import MemoryManager


async def quickstart() -> None:
    memory = await MemoryManager.create()

    await memory.store_turn(
        agent_id="research-agent",
        session_id="session-42",
        user_message="Summarise Q4 earnings for AAPL",
        assistant_message="Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...",
    )

    context = await memory.retrieve_context(
        agent_id="research-agent",
        session_id="session-42",
        query="Apple revenue Q4",
        token_budget=2000,
    )

    # context.recent_turns, recent session turns (L1)
    # context.episodic_memories, semantically relevant long-term memories (L2)
    # context.total_tokens_used, tokens consumed across both tiers
    print(context.total_tokens_used)

from actrone_memory import MemoryManager


async def quickstart() -> None:
    memory = await MemoryManager.create()

    await memory.store_turn(
        agent_id="research-agent",
        session_id="session-42",
        user_message="Summarise Q4 earnings for AAPL",
        assistant_message="Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...",
    )

    context = await memory.retrieve_context(
        agent_id="research-agent",
        session_id="session-42",
        query="Apple revenue Q4",
        token_budget=2000,
    )

    # context.recent_turns, recent session turns (L1)
    # context.episodic_memories, semantically relevant long-term memories (L2)
    # context.total_tokens_used, tokens consumed across both tiers
    print(context.total_tokens_used)

Note

Memories below the relevance threshold are left out even when the budget allows, since they add noise, not signal. Each embedder carries the threshold it was calibrated for, so the default is right for whichever one you run; memory.relevance_threshold shows it, and ACTRONE_RELEVANCE_THRESHOLD overrides it.

Step 3: scale to Redis and Qdrant (optional)

The in-memory store above is process-local and doesn't survive a restart, fine for a quickstart or a single-process app, not for production. Switch backends by installing the extras and setting ACTRONE_BACKEND=redis_qdrant; every method call above stays exactly the same.

bash

pip install "actrone-memory[production]"  # redis + qdrant + openai extras in one

pip install "actrone-memory[production]"  # redis + qdrant + openai extras in one

Tip

Hosted (fastest path): Use Redis Cloud free tier and Qdrant Cloud free cluster. Both spin up in under a minute with no local install required. Or run each service locally, see the Redis install guide and Qdrant quick start.

.env

ACTRONE_BACKEND=redis_qdrant
ACTRONE_REDIS_URL=redis://localhost:6379
ACTRONE_QDRANT_URL=http://localhost:6333
# Optional: OpenAI embeddings instead of the local embedder. Set both lines.
# ACTRONE_EMBEDDING_PROVIDER=openai
# ACTRONE_OPENAI_API_KEY=sk-...

ACTRONE_BACKEND=redis_qdrant
ACTRONE_REDIS_URL=redis://localhost:6379
ACTRONE_QDRANT_URL=http://localhost:6333
# Optional: OpenAI embeddings instead of the local embedder. Set both lines.
# ACTRONE_EMBEDDING_PROVIDER=openai
# ACTRONE_OPENAI_API_KEY=sk-...

python

from actrone_memory import MemoryManager

# Reads ACTRONE_BACKEND / ACTRONE_REDIS_URL / ACTRONE_QDRANT_URL from the environment
memory = await MemoryManager.create()

from actrone_memory import MemoryManager

# Reads ACTRONE_BACKEND / ACTRONE_REDIS_URL / ACTRONE_QDRANT_URL from the environment
memory = await MemoryManager.create()

Note

The local embedder isn't a fallback you opt into. It's the default (ACTRONE_EMBEDDING_PROVIDER=local). It uses an ONNX model (BAAI/bge-small-en-v1.5, no GPU required) when the [onnx] extra is installed, then sentence-transformers (the [local] extra), then a dependency-free hashing embedder, so it always works, with keyword-only recall in hashing mode. Set ACTRONE_EMBEDDING_PROVIDER=openai for managed, higher-recall embeddings instead.

Install and connect

The actrone-memory package gives JavaScript/TypeScript agents the same two-tier memory. It needs no services to start (an in-memory store and a local embedder are the defaults), so the on-ramp is three lines. Add fastembed and MemoryManager.create() recalls by meaning with a local model (about 130 MB, downloaded once); without it, recall is by shared keywords.

bash

npm install actrone-memory
npm install fastembed   # optional: recall by meaning, runs locally

npm install actrone-memory
npm install fastembed   # optional: recall by meaning, runs locally

Store a turn and retrieve budget-aware context, the method names are the camelCase mirror of the Python API:

typescript

import { MemoryManager } from 'actrone-memory'

// In-memory + local embedder by default: no Redis/Qdrant required to start
const memory = await MemoryManager.create()

await memory.storeTurn(
  'research-agent',
  'session-42',
  'Summarise Q4 earnings for AAPL',
  'Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...',
)

const context = await memory.retrieveContext(
  'research-agent',
  'session-42',
  'Apple revenue Q4',
  2000,
)

// context.recentTurns          : recent session turns (L1)
// context.episodicMemories     : semantically relevant long-term memories (L2)
// context.totalTokensUsed      : tokens consumed across both tiers
// context.retrievalDurationMs  : retrieval latency in milliseconds

import { MemoryManager } from 'actrone-memory'

// In-memory + local embedder by default: no Redis/Qdrant required to start
const memory = await MemoryManager.create()

await memory.storeTurn(
  'research-agent',
  'session-42',
  'Summarise Q4 earnings for AAPL',
  'Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...',
)

const context = await memory.retrieveContext(
  'research-agent',
  'session-42',
  'Apple revenue Q4',
  2000,
)

// context.recentTurns          : recent session turns (L1)
// context.episodicMemories     : semantically relevant long-term memories (L2)
// context.totalTokensUsed      : tokens consumed across both tiers
// context.retrievalDurationMs  : retrieval latency in milliseconds

For production, pass Redis (L1) and Qdrant (L2) store adapters. You bring the clients (ioredis and @qdrant/js-client-rest), the library brings the tiering. Create the Qdrant collection once, sized to the embedder:

typescript

import { MemoryManager, RedisL1Store, QdrantL2Store, buildLocalEmbedder } from "actrone-memory"
import { Redis } from "ioredis"
import { QdrantClient } from "@qdrant/js-client-rest"

const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379")
const qdrant = new QdrantClient({ url: process.env.QDRANT_URL ?? "http://localhost:6333" })

// The collection's vector size must match the embedder: 384 for bge-small, 256 for the lexical one.
const embedder = await buildLocalEmbedder()
const collection = "actrone_memory"
if (!(await qdrant.collectionExists(collection)).exists) {
  await qdrant.createCollection(collection, { vectors: { size: embedder.dimensions, distance: "Cosine" } })
}

const memory = await MemoryManager.create({
  l1: new RedisL1Store(redis),
  l2: new QdrantL2Store(qdrant, { collection }),
  embedder,
})

import { MemoryManager, RedisL1Store, QdrantL2Store, buildLocalEmbedder } from "actrone-memory"
import { Redis } from "ioredis"
import { QdrantClient } from "@qdrant/js-client-rest"

const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379")
const qdrant = new QdrantClient({ url: process.env.QDRANT_URL ?? "http://localhost:6333" })

// The collection's vector size must match the embedder: 384 for bge-small, 256 for the lexical one.
const embedder = await buildLocalEmbedder()
const collection = "actrone_memory"
if (!(await qdrant.collectionExists(collection)).exists) {
  await qdrant.createCollection(collection, { vectors: { size: embedder.dimensions, distance: "Cosine" } })
}

const memory = await MemoryManager.create({
  l1: new RedisL1Store(redis),
  l2: new QdrantL2Store(qdrant, { collection }),
  embedder,
})

Tip

Requires Node.js 22+. Budget fractions, the session cap and the relevance threshold are set via the config option on MemoryManager.create(), see Configuration.

That's it

Your agent now has budget-aware, ranked memory. With the Redis and Qdrant backends, every session survives restarts; the in-memory default lasts as long as the process. In Python, long sessions are also summarised into long-term memory after 20 turns (configurable) to keep token costs bounded.

How the retrieval pipeline works →All configuration options →LangChain, LangGraph, CrewAI integrations →

5-minute quickstart

Step 1: install the package

bash

pip install actrone-memory              # keyword recall, no downloads
pip install "actrone-memory[onnx]"      # recall by meaning, runs locally
# or with uv
uv add actrone-memory

pip install actrone-memory              # keyword recall, no downloads
pip install "actrone-memory[onnx]"      # recall by meaning, runs locally
# or with uv
uv add actrone-memory

Step 2: store and retrieve

python

from actrone_memory import MemoryManager


async def quickstart() -> None:
    memory = await MemoryManager.create()

    await memory.store_turn(
        agent_id="research-agent",
        session_id="session-42",
        user_message="Summarise Q4 earnings for AAPL",
        assistant_message="Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...",
    )

    context = await memory.retrieve_context(
        agent_id="research-agent",
        session_id="session-42",
        query="Apple revenue Q4",
        token_budget=2000,
    )

    # context.recent_turns, recent session turns (L1)
    # context.episodic_memories, semantically relevant long-term memories (L2)
    # context.total_tokens_used, tokens consumed across both tiers
    print(context.total_tokens_used)

from actrone_memory import MemoryManager


async def quickstart() -> None:
    memory = await MemoryManager.create()

    await memory.store_turn(
        agent_id="research-agent",
        session_id="session-42",
        user_message="Summarise Q4 earnings for AAPL",
        assistant_message="Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...",
    )

    context = await memory.retrieve_context(
        agent_id="research-agent",
        session_id="session-42",
        query="Apple revenue Q4",
        token_budget=2000,
    )

    # context.recent_turns, recent session turns (L1)
    # context.episodic_memories, semantically relevant long-term memories (L2)
    # context.total_tokens_used, tokens consumed across both tiers
    print(context.total_tokens_used)

Note

Step 3: scale to Redis and Qdrant (optional)

bash

pip install "actrone-memory[production]"  # redis + qdrant + openai extras in one

pip install "actrone-memory[production]"  # redis + qdrant + openai extras in one

Tip

.env

ACTRONE_BACKEND=redis_qdrant
ACTRONE_REDIS_URL=redis://localhost:6379
ACTRONE_QDRANT_URL=http://localhost:6333
# Optional: OpenAI embeddings instead of the local embedder. Set both lines.
# ACTRONE_EMBEDDING_PROVIDER=openai
# ACTRONE_OPENAI_API_KEY=sk-...

ACTRONE_BACKEND=redis_qdrant
ACTRONE_REDIS_URL=redis://localhost:6379
ACTRONE_QDRANT_URL=http://localhost:6333
# Optional: OpenAI embeddings instead of the local embedder. Set both lines.
# ACTRONE_EMBEDDING_PROVIDER=openai
# ACTRONE_OPENAI_API_KEY=sk-...

python

from actrone_memory import MemoryManager

# Reads ACTRONE_BACKEND / ACTRONE_REDIS_URL / ACTRONE_QDRANT_URL from the environment
memory = await MemoryManager.create()

from actrone_memory import MemoryManager

# Reads ACTRONE_BACKEND / ACTRONE_REDIS_URL / ACTRONE_QDRANT_URL from the environment
memory = await MemoryManager.create()

Note

Install and connect

bash

npm install actrone-memory
npm install fastembed   # optional: recall by meaning, runs locally

npm install actrone-memory
npm install fastembed   # optional: recall by meaning, runs locally

Store a turn and retrieve budget-aware context, the method names are the camelCase mirror of the Python API:

typescript

import { MemoryManager } from 'actrone-memory'

// In-memory + local embedder by default: no Redis/Qdrant required to start
const memory = await MemoryManager.create()

await memory.storeTurn(
  'research-agent',
  'session-42',
  'Summarise Q4 earnings for AAPL',
  'Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...',
)

const context = await memory.retrieveContext(
  'research-agent',
  'session-42',
  'Apple revenue Q4',
  2000,
)

// context.recentTurns          : recent session turns (L1)
// context.episodicMemories     : semantically relevant long-term memories (L2)
// context.totalTokensUsed      : tokens consumed across both tiers
// context.retrievalDurationMs  : retrieval latency in milliseconds

import { MemoryManager } from 'actrone-memory'

// In-memory + local embedder by default: no Redis/Qdrant required to start
const memory = await MemoryManager.create()

await memory.storeTurn(
  'research-agent',
  'session-42',
  'Summarise Q4 earnings for AAPL',
  'Apple reported revenue of $119.6B in Q4 2024, up 6% YoY...',
)

const context = await memory.retrieveContext(
  'research-agent',
  'session-42',
  'Apple revenue Q4',
  2000,
)

// context.recentTurns          : recent session turns (L1)
// context.episodicMemories     : semantically relevant long-term memories (L2)
// context.totalTokensUsed      : tokens consumed across both tiers
// context.retrievalDurationMs  : retrieval latency in milliseconds

typescript

import { MemoryManager, RedisL1Store, QdrantL2Store, buildLocalEmbedder } from "actrone-memory"
import { Redis } from "ioredis"
import { QdrantClient } from "@qdrant/js-client-rest"

const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379")
const qdrant = new QdrantClient({ url: process.env.QDRANT_URL ?? "http://localhost:6333" })

// The collection's vector size must match the embedder: 384 for bge-small, 256 for the lexical one.
const embedder = await buildLocalEmbedder()
const collection = "actrone_memory"
if (!(await qdrant.collectionExists(collection)).exists) {
  await qdrant.createCollection(collection, { vectors: { size: embedder.dimensions, distance: "Cosine" } })
}

const memory = await MemoryManager.create({
  l1: new RedisL1Store(redis),
  l2: new QdrantL2Store(qdrant, { collection }),
  embedder,
})

import { MemoryManager, RedisL1Store, QdrantL2Store, buildLocalEmbedder } from "actrone-memory"
import { Redis } from "ioredis"
import { QdrantClient } from "@qdrant/js-client-rest"

const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379")
const qdrant = new QdrantClient({ url: process.env.QDRANT_URL ?? "http://localhost:6333" })

// The collection's vector size must match the embedder: 384 for bge-small, 256 for the lexical one.
const embedder = await buildLocalEmbedder()
const collection = "actrone_memory"
if (!(await qdrant.collectionExists(collection)).exists) {
  await qdrant.createCollection(collection, { vectors: { size: embedder.dimensions, distance: "Cosine" } })
}

const memory = await MemoryManager.create({
  l1: new RedisL1Store(redis),
  l2: new QdrantL2Store(qdrant, { collection }),
  embedder,
})

Tip

Requires Node.js 22+. Budget fractions, the session cap and the relevance threshold are set via the config option on MemoryManager.create(), see Configuration.

That's it

How the retrieval pipeline works →All configuration options →LangChain, LangGraph, CrewAI integrations →