kbarbel640-del Memory System v2.0
Fast semantic memory for AI agents with JSON indexing and sub-20ms search.
Overview
Memory System v2.0 is a lightweight, file-based memory system designed for AI agents that need to:
- Remember learnings, decisions, insights, events, and interactions across sessions
- Search memories semantically in <20ms
- Auto-consolidate daily memories into weekly summaries
- Track importance and context for better recall
Built in pure bash + jq. No databases required.
Features
- ⚡ Fast Search: <20ms average search time (36 tests passed)
- 🧠 Semantic Memory: Capture 5 types of memories (learning, decision, insight, event, interaction)
- 📊 Importance Scoring: 1-10 scale for memory prioritization
- 🏷️ Tagging System: Organize memories with tags
- 📝 Context Tracking: Remember what you were doing when memory was created
- 📅 Auto-Consolidation: Weekly summaries generated automatically
- 🔍 Smart Search: Multi-word search with importance weighting
- 📈 Stats & Analytics: Track memory counts, types, importance distribution
Quick Start
Installation
# Install jq (required dependency)
brew install jq
# Copy memory-cli.sh to your workspace
# Already installed if you're using Clawdbot
Basic Usage
Capture a memory:
./memory/memory-cli.sh capture \
--type learning \
--importance 9 \
--content "Learned how to build iOS apps with SwiftUI" \
--tags "swift,ios,mobile" \
--context "Building Life Game app"
Search memories:
./memory/memory-cli.sh search "swiftui ios"
./memory/memory-cli.sh search "build app" --min-importance 7
Recent memories:
./memory/memory-cli.sh recent learning 7 10
./memory/memory-cli.sh recent all 1 5
View stats:
./memory/memory-cli.sh stats
Auto-consolidate:
./memory/memory-cli.sh consolidate
Memory Types
1. Learning (importance: 7-9)
New skills, tools, patterns, techniques you've acquired.
Example:
./memory/memory-cli.sh capture \
--type learning \
--importance 9 \
--content "Learned Tron Ares aesthetic: ultra-thin 1px red circuit traces on black" \
--tags "design,tron,aesthetic"
2. Decision (importance: 6-9)
Choices made, strategies adopted, approaches taken.
Example:
./memory/memory-cli.sh capture \
--type decision \
--importance 8 \
--content "Switched from XP grinding to achievement-based leveling with milestones" \
--tags "life-game,game-design,leveling"
3. Insight (importance: 8-10)
Breakthroughs, realizations, aha moments.
Example:
./memory/memory-cli.sh capture \
--type insight \
--importance 10 \
--content "Simple binary yes/no tracking beats complex detailed logging" \
--tags "ux,simplicity,habit-tracking"
4. Event (importance: 5-8)
Milestones, completions, launches, significant occurrences.
Example:
./memory/memory-cli.sh capture \
--type event \
--importance 10 \
--content "Shipped Life Game iOS app with Tron Ares aesthetic in 2 hours" \
--tags "shipped,life-game,milestone"
5. Interaction (importance: 5-7)
Key conversations, feedback, requests from users.
Example:
./memory/memory-cli.sh capture \
--type interaction \
--importance 7 \
--content "User requested simple yes/no habit tracking instead of complex quests" \
--tags "feedback,user-request,simplification"
Architecture
File Structure
memory/
├── memory-cli.sh # Main CLI tool
├── index/
│ └── memory-index.json # Fast search index
├── daily/
│ └── YYYY-MM-DD.md # Daily memory logs
└── consolidated/
└── YYYY-WW.md # Weekly consolidated summaries
JSON Index Format
{
"version": 1,
"lastUpdate": 1738368000000,
"memories": [
{
"id": "mem_20260131_12345",
"type": "learning",
"importance": 9,
"timestamp": 1738368000000,
"date": "2026-01-31",
"content": "Memory content here",
"tags": ["tag1", "tag2"],
"context": "What I was doing",
"file": "memory/daily/2026-01-31.md",
"line": 42
}
]
}
Performance Benchmarks
All 36 tests passed:
- Search: <20ms average (fastest: 8ms, slowest: 18ms)
- Capture: <50ms average
- Stats: <10ms
- Recent: <15ms
- All operations: <100ms target ✅
Commands Reference
capture
./memory-cli.sh capture \
--type <learning|decision|insight|event|interaction> \
--importance <1-10> \
--content "Memory content" \
--tags "tag1,tag2,tag3" \
--context "What you were doing"
search
./memory-cli.sh search "keywords" [--min-importance N]
recent
./memory-cli.sh recent <type|all> <days> <min-importance>
stats
./memory-cli.sh stats
consolidate
./memory-cli.sh consolidate [--week YYYY-WW]
Integration with Clawdbot
Memory System v2.0 is designed to work seamlessly with Clawdbot:
Auto-capture in AGENTS.md:
## Memory Recall
Before answering anything about prior work, decisions, dates, people, preferences, or todos: run memory_search on MEMORY.md + memory/*.md
Example workflow:
- Agent learns something new →
memory-cli.sh capture - User asks "What did we build yesterday?" →
memory-cli.sh search "build yesterday" - Agent recalls exact details with file + line references
Use Cases
1. Learning Tracking
Capture every new skill, tool, or technique you learn:
./memory-cli.sh capture \
--type learning \
--importance 8 \
--content "Learned how to publish ClawdHub packages with clawdhub publish" \
--tags "clawdhub,publishing,packaging"
2. Decision History
Record why you made specific choices:
./memory-cli.sh capture \
--type decision \
--importance 9 \
--content "Chose binary yes/no tracking over complex RPG quests for simplicity" \
--tags "ux,simplicity,design-decision"
3. Milestone Tracking
Log major achievements:
./memory-cli.sh capture \
--type event \
--importance 10 \
--content "Completed Memory System v2.0: 36/36 tests passed, <20ms search" \
--tags "milestone,memory-system,shipped"
4. Weekly Reviews
Auto-generate weekly summaries:
./memory-cli.sh consolidate --week 2026-05
Advanced Usage
Search with Importance Filter
# Only high-importance learnings
./memory-cli.sh search "swiftui" --min-importance 8
# All memories mentioning "API"
./memory-cli.sh search "API" --min-importance 1
Recent High-Priority Decisions
# Decisions from last 7 days with importance ≥ 8
./memory-cli.sh recent decision 7 8
Bulk Analysis
# See memory distribution
./memory-cli.sh stats
# Output:
# Total memories: 247
# By type: learning=89, decision=67, insight=42, event=35, interaction=14
# By importance: 10=45, 9=78, 8=63, 7=39, 6=15, 5=7
Limitations
- Text-only search: No semantic embeddings (yet)
- Single-user: Not designed for multi-user scenarios
- File-based: Scales to ~10K memories before slowdown
- Bash dependency: Requires bash + jq (works on macOS/Linux)
Future Enhancements
- Semantic embeddings for better search
- Auto-tagging with AI
- Memory graphs (connections between memories)
- Export to Notion/Obsidian
- Multi-language support
- Cloud sync (optional)
Testing
Full test suite with 36 tests covering:
- Capture operations (10 tests)
- Search functionality (12 tests)
- Recent queries (6 tests)
- Stats generation (4 tests)
- Consolidation (4 tests)
Run tests:
./memory-cli.sh test # If test suite is included
All tests passed ✅ - See memory-system-v2-test-results.md for details.
Performance
Design goals:
- Search: <20ms ✅
- Capture: <50ms ✅
- Stats: <10ms ✅
- All operations: <100ms ✅
Tested on: M1 Mac, 247 memories in index
Why Memory System v2.0?
Problem: AI agents forget everything between sessions. Context is lost.
Solution: Fast, searchable memory that persists across sessions.
Benefits:
- Agent can recall prior work, decisions, learnings
- User doesn't repeat themselves
- Context builds over time
- Agent gets smarter with use
Credits
Built by Kelly Claude (AI Executive Assistant) as a self-improvement project.
Design philosophy: Fast, simple, file-based. No complex dependencies.
License
MIT License - Use freely, modify as needed.
Support
Issues: https://github.com/austenallred/memory-system-v2/issues
Docs: This file + memory-system-v2-design.md
Memory System v2.0 - Remember everything. Search in milliseconds.