memory-system-v2

name	memory-system-v2
description	Fast semantic memory system with JSON indexing, auto-consolidation, and <20ms search. Capture learnings, decisions, insights, events. Use when you need persistent memory across sessions or want to recall prior work/decisions.
homepage	https://github.com/austenallred/memory-system-v2
metadata	{"clawdbot":{"emoji":"🧠","requires":{"bins":["jq"]},"install":[{"id":"brew-jq","kind":"brew","formula":"jq","bins":["jq"],"label":"Install jq via Homebrew"}]}}

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:

1. Agent learns something new → memory-cli.sh capture
2. User asks "What did we build yesterday?" → memory-cli.sh search "build yesterday"
3. 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.