Agents forget. Every Claude Code session starts with an empty mind, and Claude Code deletes transcripts after 30 days.
AI Maestro gives an agent memory that survives: the decisions it made and why, the facts about the systems it works on, and the things it works with and how they relate. Before it changes something, it knows what else that change touches.
What an agent learned yesterday (which host runs which service, why a migration was done a certain way, what broke the last time a bucket was moved) is gone unless someone wrote it into a file.
Claude Code deletes transcripts older than cleanupPeriodDays, 30 days by default. After that, the only record of months of an agent's work is whatever AI Maestro kept.
conversations over ten months
transcript still on disk
One of our own agents, IaC (infrastructure).
AI Maestro indexes every message into the agent's own database. That index survives the deletion, and consolidation rebuilds a conversation from it when the transcript is gone.
Not every agent needs long-term memory. An agent that answers a question, writes a function or triages an inbox does fine inside one session.
Other agents act on systems whose structure outlives any conversation: infrastructure, deployments, data, customer environments. For them the expensive mistakes are the ones where a change hits something the agent did not know was connected.
They need the entities involved (services, hosts, buckets, repositories, people) and the relations between them (runs on, stores data in, depends on, deploys to), kept current, so they can act with the consequences in view.
The model follows how human memory is usually described.
SHORT-TERM MEMORY
In people: what you hold in mind right now
The context window: the current session, the files read, the conversation so far. Lost when the session ends or is compacted.
LONG-TERM MEMORY
In people: what persists
What AI Maestro keeps across sessions.
EPISODIC
In people: what happened
The conversations: the transcript, and the agent's message index that outlives it.
SEMANTIC
In people: what is true
Memory cards (decisions, facts, preferences, lessons) and the entity graph.
PROCEDURAL
In people: how to do things
Skills. Not captured automatically yet.
CONSOLIDATION
In people: sleep turns the day into memory
A nightly run (2 AM, and older history until 8 AM) turns conversations into cards and relations.
RECALL
In people: a cue brings a memory back
The prompt: memories near it and the relations of entities it names are injected.
STRENGTH
In people: rehearsal makes a memory stronger
Recurrence: knowledge that comes up in more sessions weighs more.
FORGETTING
In people: unused memories fade
A one-off memory nobody used fades after 30 days, and comes back if it recurs.
Everything consolidation keeps is long-term memory. Recurrence does not move a memory into a different kind of memory; it makes it stronger.
Cards are written for a future session: "what the agent will need to know", not "what happened today". Progress reports, narration and task chatter are not memory.
One self-contained statement of durable knowledge, with the passages it rests on.
23blocks-api-authentication has 7 critical vulnerabilities fixed in undeployed code (v4.46.0 in prod is vulnerable); the staging environment is decommissioned, blocking a safe test and deploy of the fix.
Seen in one session.
The same knowledge came up in 2 or more separate sessions of this agent.
Seen once, never recalled, older than 30 days. Kept, not recalled; revived if it comes up again.
Before a new card is stored, AI Maestro checks whether an existing memory already states the same point; if so, the new card reinforces it instead of becoming a duplicate. Memories belong to one agent: agents do not share memory, and recurrence counts only that agent's own sessions.
Every card names the specific things it is about. Those become nodes in the agent's entity graph, shared by every card that mentions them. Between them, cards state relations, always directed and always a verb.
The verbs are fixed, and chosen for consequences:
"Related to" is not a relation: it says nothing about what a change affects.
Each statement of a relation is dated by when it was said in a conversation, and says whether it holds or has ended ("we moved the API off mini-lola"). The relation's state is its latest statement. Its weight is the number of sessions behind it.
From conversation to memory the agent can use, in the agent's own CozoDB database.
1 · INDEX
Every message, kept. Hourly and on idle, into ~/.aimaestro/agents/<id>/agent.db. Survives Claude Code's 30-day deletion.
2 · NIGHTLY CONSOLIDATION (2 AM)
3 · BACKFILL (2–8 AM)
Agents with months of history keep consolidating through the night window, newest first.
4 · RECALL
Injected at session start and on each prompt, or searched on demand.
Each agent consolidates once a night at 2 AM (its own schedule, in schedule.json). It reads every conversation with messages it has not consolidated yet, newest first: from the transcript when it is still on disk, otherwise rebuilt from the message index.
Secrets are removed before anything leaves the machine or is stored.
Each passage is judged in the context of its exchange by a small classifier (Jev, a System One model by TypeSafe AI): is it worth remembering, what kind of knowledge, how important. Most of a conversation is not memory; this step finds the candidates cheaply.
A session's candidates are read together by the host's own Claude subscription (Haiku). It writes a few cards: about one per three candidates, at most five per call, zero when nothing qualifies. Each card carries a statement, a category, its entities, its relations and its evidence.
The classifier verifies each card against its evidence, and that it does not reveal a secret value. Cards that fail are dropped.
If an existing memory states the same point, the card reinforces it instead of duplicating it. Embedding distance plus a classifier judgement, because "use X" and "do not use X" embed close together.
Entities resolve to existing nodes ("mini-lola" and "the mini-lola host" are one node), relations are recorded with the date they were said, and the classifier reads the verb the evidence supports for entity pairs a card names without one.
An agent with months of history would take months at one run per night. When a run leaves conversations behind, it records that, and during the night window (2 to 8 AM) the server keeps consolidating agents with a backlog, one at a time, round-robin, so each gets its newest history first.
An agent whose run makes no progress (a usage limit, an outage) waits for the next night. Nothing runs during the day; the Consolidate now button in the Memory tab works any time.
Each run handles about 1,000 passages and 10 summarizer calls, typically 3 to 10 conversations. Progress is saved per conversation, so a run that stops resumes where it stopped.
Cost: the classifier runs about $0.06 per 1,800 passages; the summarizer uses the host's Claude subscription (Haiku).
Memory reaches the agent automatically through the AI Maestro Claude Code hook, and on demand through the memory-search skill.
The agent's standing decisions, preferences and patterns, the ones seen in the most sessions first.
For every entity the prompt names, what the agent knows about it: its relations, current ones first, strongest first, "no longer" when one ended.
Plus the memories nearest to the prompt, favouring ones seen in more sessions.
Each memory and each entity is injected at most once per session.
A prompt asking to redeploy 23blocks-api-authentication brings:
## Memory: what you know about the things this prompt names **23blocks-api-authentication** (service) - 23blocks-api-crm depends on 23blocks-api-authentication - 23blocks-api-sales depends on 23blocks-api-authentication - 23blocks-api-search depends on 23blocks-api-authentication - Zoom uses 23blocks-api-authentication - 23blocks-api-authentication breaks 23blocks-api-platform ## Memory: notes from your past sessions on this topic - [fact ยท 2026-07-31] Staging cluster was decommissioned in June 2026 ...
On demand, through the memory-search skill:
Every injection is appended to the agent's memory-recalls.jsonl (time, session, memory ids, entity names). Consolidation folds it into each memory's access count. Only injections count; searches made by consolidation itself do not. This log is the raw data for the open question: does recalled memory change what the agent does?
Redaction is the first step of consolidation. Secrets are removed before anything leaves the machine or is stored.
Private keys, connection strings, provider tokens, KEY=value assignments, and values quoted after words like key, salt, secret or password.
A secret found once is remembered as a SHA-256 hash, never the value, and redacted wherever it appears later, even with no hint around it.
Every card is checked to make sure it does not reveal a secret value. Cards that fail are dropped.
Each agent has the skill switched on or off in its profile: Skills → Long-term memory. It is stored in the agent's own directory, so it moves with the agent.
Nightly consolidation and history backfill run for this agent.
Memories and entity relations are injected into its prompts.
Off means nothing is built and nothing is injected. What was already built is kept and remains searchable.
Settings → Memory: the model URL and API key. Each user brings their own; it is stored in ~/.aimaestro/memory-settings.json (mode 0600) and never sent back to the browser. Test connection checks it.
The summarizer uses the host's own Claude Code login. On macOS, if the server cannot read the Keychain, it runs the summarizer inside a hidden tmux session instead.
On by default for every agent. Switch it off for agents that do not need it: Agent profile → Skills.
What long-term memory does not do yet.
The recall log records what was injected; whether the agent acted on it still has to be judged from its next turns.
How to do things is not captured. Skills are the natural home for it.
Secrets are removed from memory, not from the raw index the history is rebuilt from.
A dependency nobody mentioned is not in the graph.
Free, open source, and each agent's memory lives in its own local database.