Self-Learning Agent — Knowledge Card Memory System

A production-tested memory architecture for AI agents that wake up fresh each session. Instead of one monolithic memory file that grows until it's unusable, this system uses atomic knowledge cards (~350 tokens each) searched semantically, daily logs for raw notes, and a slim master index loaded every session.

Architecture

CODEBLOCK0

Why This Works

• - MEMORY.md is tiny (~2KB). It loads fast, gives the agent orientation, and points to everything else.
• Knowledge cards are atomic. Each one covers ONE topic in ~350 tokens. Semantic search finds the right cards without loading everything.
• Daily logs are append-only scratch pads. Raw session notes, not curated.
• Cards are curated wisdom. Daily logs are raw data. The agent periodically distills daily logs into cards during maintenance.

Setup

1. Create the directory structure

CODEBLOCK1

2. Create MEMORY.md (master index)

This file is loaded every session. Keep it under 2KB. It should contain:

CODEBLOCK2

3. Add to your AGENTS.md / system prompt

CODEBLOCK3

Knowledge Card Format

Every card has YAML frontmatter and dense content:

CODEBLOCK4

Card Quality Rules

1. 1. ONE topic per card. Three insights = three cards.
2. ~350 tokens max. Dense beats verbose.
3. Zero-context readable. Include specifics (commands, paths, values).
4. Tags are searchable keywords. Lowercase, hyphenated.
5. Update, don't duplicate. If a card exists for the topic, merge new info into it.
6. No fluff. Every sentence should contain a fact, a command, or a decision.

Good Card Example

CODEBLOCK5

Bad Card Example

CODEBLOCK6

(Too vague, no specifics, no actionable info, multiple topics in one card)

Capture Triggers

Automatic (agent should capture without being asked)

• - Hard-won debugging lessons (3+ attempts to fix something)
• Configuration gotchas (things that work differently than expected)
• User corrections ("no, do it THIS way")
• Non-obvious facts about infrastructure, people, or projects
• Workflow improvements discovered during a task

Manual

• - User says /learn, "remember this", or "save this"
• User explicitly corrects the agent's approach

What NOT to Capture

• - Obvious/trivial information
• Temporary context (one-time fixes that won't recur)
• Things already in existing cards
• Conversation summaries (that's what daily logs are for)

Daily Log Format

Append to memory/YYYY-MM-DD.md:

CODEBLOCK7

Memory Maintenance

Periodically (every few days), the agent should:

1. 1. Read recent daily logs
2. Identify significant events worth preserving long-term
3. Create or update knowledge cards from insights
4. Remove outdated info from MEMORY.md
5. Update the card categories table in MEMORY.md

Think of it like a human reviewing their journal and updating their mental model.

Promotion Rules

When the same lesson appears 3+ times in cards:

• - Promote it to AGENTS.md as a permanent rule
• Mark the original card as "promoted"
• This prevents the agent from re-learning the same lesson

Session Workflow

CODEBLOCK8

Scaling

This system has been tested with:

• - ~36 knowledge cards (~350 tokens each = ~12.6K tokens total)
• Daily logs spanning months
• Semantic search via embeddings (qwen3-embedding or similar)

At this scale, semantic search finds relevant cards in <100ms. The master index stays under 2KB. The agent loads only what it needs.

If you hit 100+ cards, consider:

• - Archiving cards older than 6 months that haven't been accessed
• Splitting categories into subdirectories
• Adding a card index file per category

Comparison with Monolithic Memory