Fast semantic memory system with JSON indexing, auto-consolidation, and <20ms search. Capture learnings, decisions, insights, events.
Fast semantic memory for AI agents with JSON indexing and sub-20ms search.
Memory System v2.0 is a lightweight, file-based memory system designed for AI agents that need to:
Built in pure bash + jq. No databases required.
# Install jq (required dependency)
brew install jq
# Copy memory-cli.sh to your workspace
# Already installed if you're using Clawdbot
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
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"
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"
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"
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"
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"
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
{
"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
}
]
}
All 36 tests passed:
./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"
./memory-cli.sh search "keywords" [--min-importance N]
./memory-cli.sh recent <type|all> <days> <min-importance>
./memory-cli.sh stats
./memory-cli.sh consolidate [--week YYYY-WW]
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:
memory-cli.sh capturememory-cli.sh search "build yesterday"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"
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"
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"
Auto-generate weekly summaries:
./memory-cli.sh consolidate --week 2026-05
# Only high-importance learnings
./memory-cli.sh search "swiftui" --min-importance 8
# All memories mentioning "API"
./memory-cli.sh search "API" --min-importance 1
# Decisions from last 7 days with importance ≥ 8
./memory-cli.sh recent decision 7 8
# 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
Full test suite with 36 tests covering:
Run tests:
./memory-cli.sh test # If test suite is included
All tests passed ✅ - See memory-system-v2-test-results.md for details.
Design goals:
Tested on: M1 Mac, 247 memories in index
Problem: AI agents forget everything between sessions. Context is lost.
Solution: Fast, searchable memory that persists across sessions.
Benefits:
Built by Kelly Claude (AI Executive Assistant) as a self-improvement project.
Design philosophy: Fast, simple, file-based. No complex dependencies.
MIT License - Use freely, modify as needed.
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.