How to give your AI agent persistent memory across sessions

Your agent has a problem: it forgets everything the moment the process exits. The user tells it their deploy window is Friday mornings, their staging cluster is flaky, and they're off the week of the 22nd — and tomorrow it knows none of that. Every session starts from zero.

This tutorial fixes that. In about ten minutes you'll build a small assistant that learns facts in one session, shuts down completely, and recalls those facts days later in a fresh process. No frameworks required — just the Aether SDK and your model of choice, in TypeScript or Python.

TL;DR

• The context window isn't memory — it dies with the session. To persist across sessions, store facts outside the model and recall them on the next run.
• With Aether it's two calls: remember(text) to save a fact scoped to a user, recall(query) to pull the relevant ones back. No vector database to assemble; storage, embeddings, and semantic search are included.
• Scope memory per user with an entity id, and blend recency into recall so a newer fact outranks the stale one it replaced.

What you'll build

A terminal assistant with two runs separated by days:

1. Session 1 (Monday): the user tells the agent a few things. The agent stores them, scoped to that user with an entity id. The process exits.
2. Session 2 (Thursday): a brand-new process. The user asks a question, and the agent recalls Monday's facts with recall — blended with recency so newer facts win.

This is memory across sessions — the thing context windows can't give you, because the context window dies with the process.

Step 0: Get an API key

Sign up at platform.aetherdb.ai — the free tier ($0) is enough for everything in this tutorial. Create an API key from the dashboard and export it:

export AETHER_API_KEY="aether_..."

Step 1: Install the SDK

npm i @aether-ai/sdk

That's the whole setup. There is no second service to provision: document storage, semantic search, and embeddings are part of the platform. You don't bring a store, an embedding API, and an extraction pipeline — and you don't get three bills.

Session 1: Monday — the agent learns

Here's the whole assistant. The loop does two things on every turn: recall relevant memories before answering, and remember the exchange after.

// assistant.ts
import { Memory } from "@aether-ai/sdk";
import * as readline from "node:readline/promises";
 
// One memory space per user — everything is scoped to this entity id.
const mem = new Memory("user_8f3a", { apiKey: process.env.AETHER_API_KEY! });
 
// Bring any model you like. This is a stand-in for your chat-completion call.
async function llm(system: string, user: string): Promise<string> {
  /* call OpenAI, Anthropic, a local model — Aether doesn't care */
  return "...";
}
 
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
while (true) {
  const userMsg = await rl.question("you> ");
  if (userMsg === "exit") break;
 
  // 1. Recall: pull what this user has told us, blending similarity + recency
  const memories = await mem.recall(userMsg, { k: 5, recencyWeight: 0.3 });
 
  const system = [
    "You are a personal assistant. Facts you know about this user:",
    ...memories.map((m) => `- ${m.text}`),
  ].join("\n");
 
  const reply = await llm(system, userMsg);
  console.log(`agent> ${reply}`);
 
  // 2. Remember: store what the user said; `extract` distils atomic facts
  await mem.remember(userMsg, undefined, { extract: true });
}
 
rl.close();

Run it and have a normal conversation:

you> My deploy window is Friday mornings, before 11.
agent> Got it — Friday mornings before 11 for deploys.
you> Also, staging has been flaky since the cert rotation. Don't trust green checks there.
agent> Noted. I'll treat staging results as suspect for now.
you> exit

The process is gone. Nothing lives in RAM. The facts were stored under user_8f3a — and with extract on, distilled into atomic facts you can recall individually.

Session 2: Thursday — the agent remembers

Three days later, run the same script. New process, empty context window.

you> Can we ship the billing fix tomorrow morning?
agent> Tomorrow is Friday, which is your deploy window (before 11), so timing works.
       One flag: you told me Monday that staging has been flaky since the cert
       rotation — I'd verify the green checks manually before shipping.

No magic: the recall call at the top of the loop matched "ship tomorrow morning" against stored facts, blended in recency, and put Monday's notes in the system prompt. You can also restrict recall to a time window:

// Only recall memories from the last 7 days, newest-weighted.
const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
const recent = await mem.recall("deploy constraints", {
  since: weekAgo,     // RFC 3339 timestamp — only memories at/after this time
  recencyWeight: 0.5, // blend recency into ranking; newer facts win ties
  k: 5,
});

The same flow in Python

# pip install aether-ai
import os
from datetime import datetime, timedelta, timezone
 
from aether import Memory
 
mem = Memory("user_8f3a", api_key=os.environ["AETHER_API_KEY"])
 
# Session 1: remember (extract distils the sentence into atomic facts)
mem.remember("My deploy window is Friday mornings, before 11.", extract=True)
 
# Session 2 (days later, new process): recall, restricted to the last 30 days
since = (datetime.now(timezone.utc) - timedelta(days=30)).isoformat()
results = mem.recall("when can we deploy?", since=since, recency_weight=0.5)
for m in results:
    print(m.text, m.score)

Aether's SDKs ship in Python, TypeScript, Go, and .NET at full parity — the same remember / recall surface in all four.

Entity scoping: per-user memory isolation

The entity id is the boundary. A Memory is constructed with one entity and scopes every remember and recall to it, so an agent serving a thousand users keeps a thousand separate memory spaces — user A's facts can never surface in user B's session. There's no filter to remember to apply and no tenant logic to write.

In practice, multi-user memory is a one-line change: construct new Memory(user.id, { apiKey }) from your authenticated user's id. Use stable ids (user_8f3a, not display names), and use separate entities for separate scopes — a per-user entity for preferences, a per-project entity for shared project facts.

Recency: why yesterday beats last month

Facts about people go stale. "We deploy on Fridays" was true in March; in June the team moved to continuous deploys. A memory system that treats both statements equally will confidently tell your agent the wrong one.

recall takes a recencyWeight (0–1): at 0 it's pure semantic similarity; above 0 it blends an exponential recency decay into the ranking, so when two memories conflict the newer one wins. Time-window recall (since) goes further: for questions where only fresh state matters — current sprint, current incident, current preferences — you can exclude stale memories entirely instead of hoping ranking buries them.

The rule of thumb: raise recencyWeight for "what's true about this user," add a since window for "what's true right now."

What it costs

Everything you just built runs on the free tier — $0, the Solo Node plan. From there, pricing is a predictable flat monthly rate: Pro at $49/mo, Scale at $199/mo, Business at $499/mo. No plan meters per API call, so a chatty agent doesn't turn into a surprise invoice.

Under the hood it's Aether's own Rust storage and retrieval engine — sub-millisecond retrieval, not a wrapper around someone else's store. If you want the reasoning behind that choice, we wrote it up in Why we built our own engine for agent memory.

Next steps

• Ship it: swap the llm() stub for your real model call and construct Memory from your auth layer's user id. That's the whole production delta.
• Prefer to wire memory into your editor? Give Claude & Cursor persistent memory in 5 minutes does the same thing over MCP — no code.
• Using a framework? The raw SDK shown here is all any framework integration wraps: recall before the model call, remember after.
• Questions: support@aetherdb.ai.

Your agent's context window was never the problem. Persistence was. Now it has some.