Persistent memory for AI agents, so they never forget who you are.
Documentation · Quickstart · Framework integrations · Changelog · Blog
The TypeScript counterpart to actrone-memory
for Python. Same two-tier model, same result shapes, same one-import upgrade path.
Watch the one-minute walkthrough, narrated (1:1 and 9:16 cuts.)
Give your JS/TS agent a memory in three lines. Two-tier persistent memory (short-term session turns plus long-term semantic recall) with a pluggable store (in-memory by default; Redis/Qdrant adapters) and embeddings. Zero required dependencies for the on-ramp; MIT licensed.
It's the open-source counterpart to Actrone's governed, hosted memory, which has not launched yet. When it does, swapping one import will run every call through the governed Orchestrator (PII-tokenised, audited, policy-bounded) with the same API.
storeTurn ─────────────▶ L1 short-term session turns (recency, token-budgeted)
injectMemory ──┐
└───────▶ L2 long-term semantic memory (embeddings)
retrieveContext(query, budget)
│ in parallel: fetch recent turns | embed query → L2 search
│ (+ optional hybrid BM25/RRF, + optional rerank)
│ → optional redaction by sensitivity
│ → allocate token budget → prune to fit
▼
{ recentTurns, episodicMemories } ── prepend to your prompt
npm install actrone-memoryimport { MemoryManager } from "actrone-memory";
const mm = await MemoryManager.create(); // in-memory store, no services, no API key
await mm.storeTurn("support-bot", "sess-1", "What's your refund policy?", "Within 5 days.");
await mm.injectMemory("support-bot", "The customer is on the Enterprise plan.", 0.9);
const ctx = await mm.retrieveContext("support-bot", "sess-1", "Which plan is the customer on?", 4096);
// ctx.recentTurns : the recent conversation, pruned to the session budget
// ctx.episodicMemories : relevant long-term memories, here the Enterprise plan factKeyword recall or semantic recall. With nothing else installed, create() uses the
lexical LocalEmbedder: it recalls memories that share words with the query, and says so
once with a process warning. Install fastembed and create() switches to
bge-small-en-v1.5, still on your machine, which recalls by meaning: "food allergies" then
finds "The user is allergic to peanuts." The first run downloads the model (about 130 MB)
to ~/.cache/actrone-memory/fastembed, or to FASTEMBED_CACHE_PATH if you set it.
npm install fastembed// Self-hosted (this library)
import { MemoryManager } from "actrone-memory";
const mm = await MemoryManager.create();
// Hosted + governed (Actrone Orchestrator): same methods, same result shapes.
// Only the import line changes; the rest of your code keeps using `MemoryManager`.
import { ActroneMemoryManager as MemoryManager } from "@actrone/sdk";
const mm = new MemoryManager({ apiKey: process.env.ACTRONE_API_KEY! });MemoryManager (all methods async):
| Method | Purpose |
|---|---|
create(options?) |
Build a manager (in-memory default; pass l1/l2/embedder for Redis/Qdrant/real embeddings) |
storeTurn(agentId, sessionId, userMessage, assistantMessage, toolResults?) |
Persist a conversation turn → turn id |
retrieveContext(agentId, sessionId, query, tokenBudget, options?) |
Assemble budget-bounded context (4-phase: parallel fetch → allocate → rank → prune); options.redact masks memories by sensitivity |
injectMemory(agentId, content, importance?, sessionId?, topicTags?) |
Write a long-term fact → memory id |
searchMemories(agentId, query, limit?, options?) |
Semantic search over long-term memory; options.redact as above |
deleteMemory(agentId, memoryId) |
Remove a memory |
clearSession(agentId, sessionId) |
Clear session turns (long-term memories persist) |
getSessionMetadata(agentId, sessionId) |
Session stats, or null if expired |
The defaults, InMemoryStore plus the best local embedder, need no services. Swap them
for durability or a hosted embedding model:
const mm = await MemoryManager.create({
l1: myRedisStore, // implements L1Store
l2: myQdrantStore, // implements L2Store
embedder: myOpenAIEmbedder, // implements Embedder; set relevanceThreshold for it (see Configuration)
});L1Store, L2Store, and Embedder are small interfaces, so you can implement them
against any backend without touching the manager. What ships:
| Tier | Adapters |
|---|---|
| Hot session (L1) | InMemoryStore (default), RedisL1Store, PostgresL1Store |
| Long-term semantic (L2) | InMemoryStore (default), QdrantL2Store, PgVectorL2Store |
Every adapter takes an injected client, so this package has no hard ioredis,
@qdrant/js-client-rest or pg dependency.
Redis-compatible servers need no separate adapter. RedisL1Store uses only standard
commands, so Valkey, DragonflyDB, ElastiCache and Upstash work with it as-is.
Postgres runs both tiers, which is the "no new infrastructure" option: if you already run Postgres with the pgvector extension, memory needs no extra service at all. One pool serves both.
import { Pool } from "pg";
import { MemoryManager, PostgresL1Store, PgVectorL2Store } from "actrone-memory";
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const l1 = new PostgresL1Store(pool);
const l2 = new PgVectorL2Store(pool, { dimensions: 1536 });
await l1.ensureSchema();
await l2.ensureSchema();
const mm = await MemoryManager.create({ l1, l2, embedder: myEmbedder });The built-in adapters have no privileged access: they implement L1Store and L2Store like
anything else would. Any engine that can satisfy those interfaces plugs in without touching
the manager, and the store you pass is used as-is, so no built-in backend is constructed or
connected behind it.
import { MemoryManager } from "actrone-memory";
class MyWeaviateStore implements L2Store {
async upsert(entry) { /* ... */ }
async search(params) { /* ... */ }
async delete(memoryId) { /* ... */ }
async deleteAgentMemories(agentId) { /* ... */ }
}
const mm = await MemoryManager.create({ l2: new MyWeaviateStore(client) });Two things worth knowing before you write one:
- Return the embedding with each search hit if you rank with the bundled
hybridRankhelper, which recomputes cosine locally. If your database ranks server-side and does not return vectors (Pinecone needsincludeValues), usefuseChannelswith its own scores instead, the wayQdrantL2Storedoes. close()andtryAcquireSummaryLock()are optional. Implementclose()if your store opens its own connection;MemoryManager.close()calls it. Implement the lock with a single atomic operation if you want fleet-wide background-job coordination.
To make that a supported extension point rather than a claim, the package ships the same conformance suite the built-in stores are held to:
import { checkL1Store, checkL2Store } from "actrone-memory/testing";
await checkL2Store(() => new MyWeaviateStore(client), { dimensions: 1536 });It checks the behaviours the type system cannot: turns come back oldest-first, n windows
from the end, a search never returns another agent's memories, threshold, limit and
contentTypes are honoured, an upsert replaces rather than duplicates, erasure is scoped,
and a summary lock admits one holder. Each failure throws ConformanceError naming the
requirement. The Python library ships the same suite as actrone_memory.testing against the
same contract, so an adapter in either language is held to the same bar.
This library is local-first by default: the built-in embedder runs in-process and fact extraction is opt-in, so with the defaults nothing leaves your machine: no API key, no egress. It is also cloud-capable, so you can inject any OpenAI-compatible embedder or extractor.
Important, and this is exactly where PII protection holds. The sensitivity classification (none/low/pii/sensitive) is
produced by the extraction step, and that step (and any real embedder) sees the raw text. So PII
protection here holds only for local models (in-process or a local Ollama endpoint, so zero-egress). If you
point extraction or embeddings at a cloud provider, the raw text, including PII-classified content, is
sent to that provider. This library does not tokenise it first.
Redaction on read. To keep tagged personal data out of what you send a model, turn on redaction for
every read with config: { redactSensitivities: ["pii", "sensitive"] }, or for one call with redact:
const ctx = await mm.retrieveContext(agentId, sessionId, query, 4096, { redact: ["pii", "sensitive"] });
// A fact tagged pii comes back as "[redacted: pii]", with its embedding dropped.It covers retrieveContext() and searchMemories(), and so every adapter built on them. Stored memories
do not change, and redact: [] turns it off for a single call. It acts only on tags: raw turns are never
classified, so they are never masked, and the library does not detect personal data on its own.
Actrone's hosted platform, when it launches, will add MAL (Memory Abstraction Layer) to tokenise PII before inference, so cloud models never receive the raw values. It has not launched yet. Short form: local-first by default; cloud-capable; PII stays on your machine only with local models.
Adapters live in actrone-memory/adapters and are structural: none imports its framework at
runtime, so nothing is bundled and the base install pulls only zod. Install the framework you use;
the versions below are the optional peerDependencies, each type-checked against the real framework
at its oldest and newest release. npm refuses to install next to a framework version outside its range
(ERESOLVE), so a weekly CI job also type-checks each framework's next major, which is how a range
widens when that major ships. Every framework recipe is CI-typechecked
against the current adapter API (examples/frameworks/); run npx actrone-memory add <framework> for
a copy-paste recipe.
| Framework | Adapter | Tested peer version |
|---|---|---|
| Vercel AI SDK | vercelMemory |
ai >=5 <8 |
| LangChain.js | langchainMemory / langchainChatHistory |
@langchain/core >=0.2 <2 |
| LangGraph.js | langgraphMemory |
@langchain/langgraph >=0.1 <2 |
| Mastra | mastraMemory |
@mastra/core >=0.10 <2 |
| LlamaIndex.TS | llamaindexMemory / llamaindexChatMemory |
llamaindex >=0.8 <1 |
| OpenAI Agents JS | openaiAgentsMemory |
@openai/agents >=0.1 <1 |
| Firebase Genkit | genkitMemory |
genkit >=1.0.4 <2 |
| VoltAgent | voltagentMemory |
@voltagent/core >=0.1.14 <3 |
| Claude Agent SDK | claudeAgentMemory |
@anthropic-ai/claude-agent-sdk >=0.1 <1 |
| Cloudflare Agents | cloudflareAgentsMemory |
agents >=0.0.37 <1 |
| Inngest AgentKit | inngestAgentKitMemory |
@inngest/agent-kit >=0.5 <1 |
Adapter depth (honest scope). Most adapters are lightweight, framework-idiomatic
helpers: recall returns a governed context string you inject as system/instructions,
and remember persists the completed turn. Two go deeper and implement the
framework's own message-history contract: langchainChatHistory (a governed
BaseListChatMessageHistory duck-type for RunnableWithMessageHistory) and
llamaindexChatMemory (the current LlamaIndex.TS Memory shape). This is not full
parity with the Python library's per-framework memory subclasses; it is the pragmatic
TS surface, and every recipe is CI-typechecked against the current adapter API. The
framework-agnostic core (recall / remember / memoryFor) works with any framework.
MemoryManager.create({ config }) takes a partial MemoryConfig merged over
DEFAULT_CONFIG; unset keys keep their defaults. Common knobs:
| Key | Purpose |
|---|---|
relevanceThreshold |
Minimum similarity for a long-term memory to be recalled. Leave unset to use the embedder's calibrated value: 0.3 for the lexical LocalEmbedder, 0.63 for bge-small-en-v1.5, and 0.7 for an embedder that declares none. mm.relevanceThreshold shows the value in use. |
maxEpisodicMemories |
Cap on long-term memories considered per retrieval. |
budgetFractionSession / budgetFractionEpisodic |
How the token budget is split between recent turns and long-term memory. |
hybridRetrieval |
Fuse lexical (BM25) + dense signals via reciprocal-rank fusion. |
relevanceWeight / recencyWeight |
Balance semantic relevance against recency in L2 ranking. |
redactSensitivities |
Sensitivity classes masked whenever memories are read, for example ["pii", "sensitive"]. Matching memories come back as [redacted: <class>]. Default: none. |
Stores and embeddings are injected, not configured by env. Pass l1 / l2 /
embedder / reranker to create(). The defaults need no services. Pass
embedder: new LocalEmbedder() for deterministic, offline recall in tests even when
fastembed is installed.
Similarity scales differ between models, so a threshold chosen for one model is wrong for
another: the lexical embedder scores relevant text around 0.24, while bge-small scores
unrelated text around 0.48. For your own embedder, set relevanceThreshold to a value you
have measured on your data, or declare relevanceThreshold on the embedder itself.
The retrieveContext recall pipeline (GitHub renders the diagram):
flowchart TD
Q["retrieveContext(query, budget)"] -->|"in parallel"| L1["fetch recent L1 turns"]
Q -->|"in parallel"| EMB["embed query"]
EMB --> L2["L2 semantic search"]
L2 -->|"hybridRetrieval"| RRF["+ BM25 / reciprocal-rank fusion (optional)"]
RRF --> RR["+ cross-encoder rerank top-K (optional)"]
L2 --> RR
RR --> RED["redact by sensitivity (optional)"]
L1 --> ALLOC["allocate token budget<br/>session vs episodic"]
RED --> ALLOC
ALLOC --> PRUNE["priority-weighted prune to fit"]
PRUNE --> OUT["{ recentTurns, episodicMemories }"]
retrieveContextreturns noepisodicMemories. Nothing cleared the admission threshold for that query;mm.relevanceThresholdshows the value in use. If you saw theACTRONE_MEMORY_LEXICAL_EMBEDDERwarning, recall is keyword-only: the query must share words with the memory. Installfastembedfor recall by meaning.create()pauses on first run. Withfastembedinstalled, the firstcreate()downloads bge-small-en-v1.5 (about 130 MB). Later runs load it from the cache offline.TokenBudgetError: tokenBudget must be > 0.retrieveContextneeds a positive token budget (e.g.4096).- Redis/Qdrant not used. Stores are injected, not auto-detected, so pass
l1: new RedisL1Store(...)/l2: new QdrantL2Store(...)toMemoryManager.create(). npm warnabout an optional peer version. Adapters are structural (nothing is imported at runtime); the peer ranges only make the tested version machine-legible. Install the framework you actually use; ignore the others' warnings.- CLI recipe.
npx actrone-memory add <framework>prints an install plus copy-paste recipe;--write <file>creates one new self-contained file and never overwrites.
npm install
npm run typecheck && npm test && npm run buildfastembed is not a dev dependency, so the suite runs on InMemoryStore and the lexical
LocalEmbedder: offline, with no key, no model download and no Docker.
| Page | What's in it |
|---|---|
| API reference | Generated TypeDoc for every export |
| Framework recipes | One CI-typechecked example per adapter |
| Changelog | What changed in each release |
| Contributing | Dev environment setup and how to submit a PR |
| Security policy | How to report a vulnerability privately |
actrone-memory is the open-source memory layer behind Actrone, a
platform in development for running AI agents under governance: durable task execution,
tool supervision, PII tokenisation before inference, and an audit trail.
You never have to adopt any of that. This library is MIT and works standalone forever. If you outgrow self-hosting once the platform launches, the migration will be the one-import change shown above.
MIT. Free to use in any project, commercial or otherwise.
