memory-system-v2

# 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

```bash
# 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:**
```bash
./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:**
```bash
./memory/memory-cli.sh search "swiftui ios"
./memory/memory-cli.sh search "build app" --min-importance 7
```

**Recent memories:**
```bash
./memory/memory-cli.sh recent learning 7 10
./memory/memory-cli.sh recent all 1 5
```

**View stats:**
```bash
./memory/memory-cli.sh stats
```

**Auto-consolidate:**
```bash
./memory/memory-cli.sh consolidate
```

## Memory Types

### 1. Learning (importance: 7-9)
New skills, tools, patterns, techniques you've acquired.

**Example:**
```bash
./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:**
```bash
./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:**
```bash
./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:**
```bash
./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:**
```bash
./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

```json
{
  "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
```bash
./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
```bash
./memory-cli.sh search "keywords" [--min-importance N]
```

### recent
```bash
./memory-cli.sh recent <type|all> <days> <min-importance>
```

### stats
```bash
./memory-cli.sh stats
```

### consolidate
```bash
./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:**
```markdown
## 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:
```bash
./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:
```bash
./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:
```bash
./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:
```bash
./memory-cli.sh consolidate --week 2026-05
```

## Advanced Usage

### Search with Importance Filter
```bash
# 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
```bash
# Decisions from last 7 days with importance ≥ 8
./memory-cli.sh recent decision 7 8
```

### Bulk Analysis
```bash
# 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:**
```bash
./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.**