Illustrative diagram · agents write to the brain (rose); it processes and returns briefings (cyan) at the start of each session.
🧠 The problem: agents that forget
You run several agents—one for development, one autonomous agent for tasks, and automations for workflows. Each keeps its own context and forgets everything between sessions. When one discovers something important, the others never find out. That’s the problem that justifies a shared brain.
⚠️ Why key-value isn’t enough
Existing solutions are either single-machine, require a paid cloud service, or treat memory as a flat key-value bag — without understanding that a fact and one event are fundamentally different things, with different life cycles. Real memory needs types.
✓ With a shared brain
- ✓What one agent learns becomes available to everyone.
- ✓Works across machines, tools, and frameworks.
- ✓The session starts with an understanding of what changed since last time.
✗ Without it
- ✗Each agent lives in its own context bubble.
- ✗Total amnesia at the start of every new session.
- ✗Valuable discoveries don't propagate.
Separate context.
Forget between sessions.
Discoveries get stuck.
Shared brain.
🧩 The 4 types of memory
Here’s the central idea: a fact and an event are different things. The system understands four types, each with its own lifecycle and mutation rule. This taxonomy is what separates a real memory system from a pile of strings.
| Type | Behavior | Example |
|---|---|---|
| event | Append-only, immutable. You don’t update history; you record it. | "Workflow failed at 3 a.m." |
| fact | Upsert by key. New fact supersedes the old one. | "API status: healthy" |
| status | In-place update by subject. The latest one wins. | "migration: 70%" |
| decision | Append-only with reasoning. The why matters. | "Postgres instead of MySQL because..." |
📊 It’s not taxonomy for its own sake
Typing tells the system how each memory should behave when it changes: a fact is superseded, a status is overwritten, an event is permanent, and a decision is a reasoning record. Different data, different rules. Without this, everything becomes the same blob, and you lose the ability to version it and trust what’s active.
Immutable.
Upsert by key.
Last one wins.
Keep the why.
🔄 The Memory Lifecycle
Each memory goes through a pipeline. That’s what keeps the brain useful instead of turning into a repository that only grows. Four mechanisms work together: deduplication, supersession chains, confidence decay, and LLM consolidation.
Deduplication
Content is hashed with SHA-256 when saved. Exact duplicates are caught; consolidation still catches near-duplicates at 92% semantic similarity.
Supersedes chain
Recorded a fact with the same key? The old one is marked inactive, and the new one points back to it. Free version history, with no manual work.
Trust decay
Facts and status lose ~2%/day if no one accesses them. Search ranks by similaridade × confiança. Old knowledge sinks on its own; access resets the clock. Events and decisions don’t decay—they’re history.
LLM consolidation (every 6h)
A background process analyzes new memories: merges duplicates, flags contradictions, discovers connections, and extracts cross-cutting insights. It’s a librarian that organizes knowledge instead of letting it pile up.
💡 The brain improves while you sleep
Periodic consolidation is the differentiator. While ordinary systems only accumulate, this one reorganizes: the first pass after an upgrade automatically cleared hundreds of junk memories. Decay + consolidation = memory that ages like human memory, forgetting what’s irrelevant.
🛡️ Security and isolation
Shared memory among agents that run without supervision is only viable with a well-designed gatekeeper. The API is the gatekeeper: no agent touches the database directly. They can store and retrieve—and that's it.
✓ What an agent CAN do
- ✓Record and search memories through validated endpoints.
- ✓Read briefs, stats, and entities.
✗ What NOT to do
- ✗Deleting memories or dropping tables.
- ✗Bypass credential cleanup.
- ✗Access the database directly or alter someone else's memory.
🔐 Credential scrubbing
All content is cleaned before storage: API keys, JWTs, SSH keys, passwords, and base64 secrets are redacted automatically. Agents share context freely without leaking credentials into long-term memory.
⚠️ The worst case is good data, not destruction
It’s by design: if an autonomous agent hallucinates or goes off script, the worst it can do is write bad data — cannot destroy good data. Add timing-safe auth and rate limiting (10 failures/min = lockout). The basics done right.
API validates everything.
No credentials.
Doesn’t touch the database.
Timing-safe + limit.
📊 Session briefings
This is where coordination between agents actually happens — passively. Every session starts with a question: "what's happened since I was last here?". The briefing endpoint returns updates from all the other agents, excluding your own.
Illustrative recreation of a briefing call (not a real screenshot):
In practice: the dev agent opens a session on Friday morning and already knows that a workflow failed on Thursday night and another agent discovered something about a client’s ranking—without checking logs or remembering to look. The system surfaces it.
✓ Good briefing practices
- ✓Call in beginning for each session.
- ✓Exclude your own entries (they’re already known).
- ✓Sort by importance, then recency.
✗ Antipatterns
- ✗Rely on human memory to “go check the logs.”
- ✗Bring everything without filtering by importance—it becomes noise.
- ✗Include its own entries and clutter the brief.
💡 Practical tip
Treat the briefing as the agent’s mandatory “good morning.” Put the call at the start of your session-opening flow—this makes coordination between agents a system habit, not something that depends on you remembering. It’s the natural counterpart to /sessionend: one opens, the other closes.
Timestamp.
Exclude itself.
By type.
Effortless coordination.
🔥 The /sessionend Ritual
O /sessionend is a skill that closes the loop of compound intelligence. At the end of each session, it turns what happened into institutional memory. The point isn’t just to summarize — it’s to evaluate honestly and save the result in a structured way.
Gather — collect the artifacts
Runs git log, diff, status and reviews the conversation history: what was requested, which tools were used, what worked, and what needed a retry.
Reflect — reflect honestly
What went well, what went poorly, and how it could have been better. "Everything went well" is not valid reflection — if something was suboptimal, name it. That’s the rule that adds the most value.
Store — save in memory
Saves a structured summary (what was done · what went well · what went poorly · how to improve · relevant to other agents) under a dated topic.
Update — update local memory
Only save what's genuinely new: preferences, project facts, information about the user. Update the index. Don't save again what has already been captured.
♾️ Why this composes
The end of a session feeds the consolidation, which feeds the briefing of the next session. Each session makes all future sessions smarter—not just for that agent, but for everyone. It's the same self-improvement loop as 6.1 (Workflow Spotter) and 6.2 (Taproot), now at the system memory level.
"O que aconteceu desde a última vez que estive aqui? Traga o briefing de todos os outros agentes desde ontem, ordenado por importância. Exclua minhas próprias entradas."
/sessionend # (ou, sem a skill instalada:) "Encerre a sessão: reúna git log/diff, reflita com honestidade (o que foi bem, o que foi mal — 'tudo certo' NÃO vale), guarde um resumo estruturado e atualize a memória local só com o novo."
📤 Output example
Illustrative recreation of the final summary that /sessionend prints for the user (not a real screenshot):
🏋️ Hands-on exercises
Classify 5 memories
Choose 5 pieces of information from your recent work and classify each as event, fact, status, or decision. Explain why the type matters in each case.
Design your brief
List your agents/tools and write the briefing question each one would ask at startup. Define the sorting criteria (importance × recency).
Create a runnable /sessionend SKILL.md
Write a shutdown skill that adapts to any memory backend. Skeleton:
Save in ~/.claude/skills/sessionend/SKILL.md and test by typing "/sessionend" at the end of a work session. Works with any memory backend (or locally only).
📌 Module summary
You’ve reached the end
This is the final lesson of the course. From the anatomy of SKILL.md (T1) to multi-agent memory, you've covered the full path of Claude Skills in Practice.