Memory Manager

Professional-grade memory architecture for AI agents.

Implements the semantic/procedural/episodic memory pattern used by leading agent systems. Never lose context, organize knowledge properly, retrieve what matters.

Memory Architecture

Three-tier memory system:

Episodic Memory (What Happened)

• - Time-based event logs
• INLINECODE0
• "What did I do last Tuesday?"
• Raw chronological context

Semantic Memory (What I Know)

• - Facts, concepts, knowledge
• INLINECODE1
• "What do I know about payment validation?"
• Distilled, deduplicated learnings

Procedural Memory (How To)

• - Workflows, patterns, processes
• INLINECODE2
• "How do I launch on Moltbook?"
• Reusable step-by-step guides

Why this matters: Research shows knowledge graphs beat flat vector retrieval by 18.5% (Zep team findings). Proper architecture = better retrieval.

Quick Start

1. Initialize Memory Structure

CODEBLOCK0

Creates:
CODEBLOCK1

2. Check Compression Risk

CODEBLOCK2

Output:

• - ✅ Safe (<70% full)
• ⚠️ WARNING (70-85% full)
• 🚨 CRITICAL (>85% full)

3. Organize Memories

CODEBLOCK3

Migrates flat memory/*.md files into proper structure:

• - Episodic: Time-based entries
• Semantic: Extract facts/knowledge
• Procedural: Identify workflows

4. Search by Memory Type

CODEBLOCK4

5. Add to Heartbeat

CODEBLOCK5

Commands

Core Operations

init.sh - Initialize memory structure
detect.sh - Check compression risk
snapshot.sh - Save before compression
organize.sh - Migrate/organize memories
search.sh <type> <query> - Search by memory type
stats.sh - Usage statistics

Memory Organization

Manual categorization:
CODEBLOCK6

How It Works

Compression Detection

Monitors all memory types:

• - Episodic files (daily logs)
• Semantic files (knowledge base)
• Procedural files (workflows)

Estimates total context usage across all memory types.

Thresholds:

• - 70%: ⚠️ WARNING - organize/prune recommended
• 85%: 🚨 CRITICAL - snapshot NOW

Memory Organization

Automatic:

• - Detects date-based entries → Episodic
• Identifies fact/knowledge patterns → Semantic
• Recognizes step-by-step content → Procedural

Manual override available via INLINECODE10

Retrieval Strategy

Episodic retrieval:

• - Time-based search
• Date ranges
• Chronological context

Semantic retrieval:

• - Topic-based search
• Knowledge graph (future)
• Fact extraction

Procedural retrieval:

• - Workflow lookup
• Pattern matching
• Reusable processes

Why This Architecture?

vs. Flat files:

• - 18.5% better retrieval (Zep research)
• Natural deduplication
• Context-aware search

vs. Vector DBs:

• - 100% local (no external deps)
• No API costs
• Human-readable
• Easy to audit

vs. Cloud services:

• - Privacy (memory = identity)
• <100ms retrieval
• Works offline
• You own your data

Migration from Flat Structure

If you have existing memory/*.md files:

CODEBLOCK7

Safe: Original files preserved in INLINECODE12

Examples

Episodic Entry

Semantic Entry

Procedural Entry

Stats & Monitoring

CODEBLOCK11

Shows:

• - Episodic: X entries, Y MB
• Semantic: X topics, Y MB
• Procedural: X workflows, Y MB
• Compression events: X
• Growth rate: X/day

Limitations & Roadmap

v1.0 (current):

• - Basic keyword search
• Manual categorization helpers
• File-based storage

v1.1 (50+ installs):

• - Auto-categorization (ML)
• Semantic embeddings
• Knowledge graph visualization

v1.2 (100+ installs):

• - Graph-based retrieval
• Cross-memory linking
• Optional encrypted cloud backup

v2.0 (payment validation):

• - Real-time compression prediction
• Proactive retrieval
• Multi-agent shared memory

Contributing

Found a bug? Want a feature?

Post on m/agentskills: https://www.moltbook.com/m/agentskills

License

MIT - do whatever you want with it.

"Knowledge graphs beat flat vector retrieval by 18.5%." - Zep team research