Chat Memory

Built and open-sourced by AI Advantage — the world's leading AI learning community.
We teach 40,000+ people how to actually use AI. This skill is how our own agents remember everything.
Want to learn more? Join us at aiadvantage.ai.

Solve the #1 problem with long-running AI agents: knowledge loss after context compaction.

The Problem

When sessions compact (summarize old messages to free context), specific details are lost:
names, decisions, file paths, reasoning. The agent retains a summary but loses the ability
to recall "What exactly did Annika say?" or "When did we decide to use v6 format?"

Most memory skills on ClawHub are just SKILL.md instructions — "write stuff to MEMORY.md."
That's not a solution. This skill ships real scripts that do real work.

The Solution: Three-Layer Memory Architecture

CODEBLOCK0

All three layers live under memory/ and are automatically vectorized by OpenClaw's
memory search, creating a navigational hierarchy: glossary finds the right session,
session provides the details.

Setup (run once)

Step 1: Convert existing sessions to Markdown

CODEBLOCK1

This scans all JSONL session logs in ~/.openclaw/agents/*/sessions/ and converts
them to memory/sessions/session-YYYY-MM-DD-HHMM-*.md. Truncates long assistant
responses to 2KB, skips system messages, tracks state to avoid re-processing.

Options:

• - --new — Only convert sessions not yet processed (for incremental runs)
• INLINECODE4 — Specify agent ID (default: main)

Step 2: Build the glossary

CODEBLOCK2

Scans all session transcripts and builds memory/SESSION-GLOSSAR.md with:

• - People — Who was mentioned, in how many sessions, date ranges
• Projects — Which projects discussed, with relevant topic tags
• Topics — Categorized themes (Email Drafts, Website Build, Security, etc.)
• Timeline — Per-day summary (session count, people, topics)
• Decisions — Extracted decision-like statements with dates

Options:

• - --incremental — Only process new sessions (uses cached scan state)

Step 3: Set up cron jobs for auto-updates

Create two cron jobs (use a cheap model like Gemini Flash):

Job 1: Session sync + glossary rebuild (every 4-6 hours)
CODEBLOCK3

Optional Job 2: Pre-compaction memory flush check
Already built into AGENTS.md by default — just ensure the agent writes to
memory/YYYY-MM-DD.md before each compaction.

Customizing Entity Detection

Edit scripts/build-glossary.py to add your own known people and projects:

CODEBLOCK4

The glossary also detects topics via regex patterns. Add new patterns in the
topic_patterns dict for your domain.

How It Works With memory_search

Once set up, memory_search("Alice project decision") will find:

1. 1. The glossary entry for Alice (which sessions she appears in)
2. The actual session transcript where the decision was discussed
3. Any MEMORY.md entry about Alice

This gives the agent a navigation layer (glossary) plus detail access
(transcripts) — much better than either alone.

File Structure After Setup

CODEBLOCK5

Cron Memory Optimizer

Cron jobs run in isolated sessions with zero memory context. The optimizer analyzes your cron jobs and suggests memory-enhanced versions:

CODEBLOCK6

This scans ~/.openclaw/cron/jobs.json, identifies jobs that would benefit from memory context, and generates memory/cron-optimization-report.md with before/after prompts and implementation guidance.

Example optimization:
CODEBLOCK7

The script is conservative (suggests only, never auto-modifies) and skips monitoring jobs that don't need context.

Sharing Memory Context with Cron Jobs, Subagents & Telegram Sessions

One of the biggest challenges in multi-session AI systems is context isolation. Here's how to share memory context across different execution environments:

For Cron Jobs

The problem: Cron jobs run in isolated sessions with zero memory context, making them blind to recent activities, people, and decisions.

The solution: Prepend a "memory preamble" to cron job prompts that instructs the agent to search memory before starting:

CODEBLOCK8

The cron-optimizer.py script analyzes your existing cron jobs and automatically suggests which ones would benefit from memory context. It generates a detailed report with before/after prompts.

Example transformation:
CODEBLOCK9

For Subagents (sessions_spawn)

The problem: Subagents start with empty context and don't know about recent activities or ongoing projects.

The solution: Include memory instructions in the task prompt when spawning subagents:

CODEBLOCK10

Tips:

• - Be specific with memory_search keywords for best results
• Include both recent (SESSION-GLOSSAR.md) and long-term (MEMORY.md) context
• Consider what the subagent needs to know to do its job effectively

For Telegram Group Sessions

The problem: Group sessions share the workspace but don't automatically know about the memory system or recent activities discussed in other sessions.

The solution: Two approaches depending on your setup:

Method 1: Push context via sessions_send
CODEBLOCK11

Method 2: Add memory awareness to AGENTS.md
Add guidance to your AGENTS.md so group sessions know to search memory:
CODEBLOCK12

Tips:

• - Group sessions can access the memory system if they know to use it
• Include memory search instructions in your group-specific agent guidelines
• Consider pushing critical updates from main to group sessions when decisions are made

For Knowledge Bases (Vectorized Databases)

If you have custom vectorized knowledge bases (e.g., using sentence-transformers), make them accessible across sessions:

Method 1: Query scripts
CODEBLOCK13

Method 2: Workspace storage
CODEBLOCK14

Method 3: Integration prompts
Include the script path in cron job and subagent prompts:
CODEBLOCK15

The key is making knowledge discovery automatic and standardized across all execution contexts — main session, cron jobs, subagents, and group sessions should all follow the same memory-aware patterns.

Tips

• - Run the full rebuild (python3 scripts/build-glossary.py without --incremental)

occasionally to pick up improvements to entity detection

• - The glossary is most useful when KNOWNPEOPLE and KNOWNPROJECTS are populated —

spend 5 minutes adding your key contacts and projects

• - For agents that run 24/7, the cron job keeps everything current automatically
• Session transcripts can get large (our 297 sessions = 24MB) — this is fine,

OpenClaw's vector search handles it efficiently

• - Use the cron optimizer after setting up memory to enhance existing automation

Why This Exists

We run OpenClaw agents 24/7 for real work — client projects, research pipelines, content
production. After a week we had 300+ sessions and our agents kept forgetting critical
details after compaction. We built this to fix it, and it worked so well we open-sourced it.

What makes this different from other memory skills:

• - ✅ Real Python scripts — not just "instructions for the agent"
• ✅ Three-layer architecture — curated + auto-glossary + raw transcripts
• ✅ Cron automation — runs in the background, zero manual work
• ✅ Glossary with entity detection — people, projects, decisions, timeline
• ✅ Cron optimizer — makes your existing cron jobs context-aware
• ✅ Clean security score — no suspicious flags, no external dependencies
• ✅ Battle-tested — 300+ sessions, running in production daily

---

Built with 🔥 by AI Advantage — Join 40,000+ people learning to build with AI.
We don't just teach AI — we build with it every day. This skill is proof.