# Next Session Guide - LLMemory

## Quick Start for Next Developer/Agent

**Project:** LLMemory - AI Agent Memory System  
**Current Phase:** Phase 0 Complete (Planning + Prototype)  
**Next Phase:** Phase 1 - MVP Implementation  
**Estimated Time to MVP:** 12-15 hours

## What's Been Done

### ✅ Completed
1. **Planning & Architecture**
   - Two competing investigate agents analyzed implementation strategies
   - Comprehensive SPECIFICATION.md created (data model, search algorithms, CLI design)
   - Detailed IMPLEMENTATION_PLAN.md with step-by-step checkboxes
   - ARCHITECTURE.md with algorithm pseudo-code and performance targets

2. **Project Structure**
   - Directory created: `/home/nate/nixos/shared/linked-dotfiles/opencode/llmemory/`
   - package.json configured with dependencies
   - .gitignore set up
   - bin/memory executable created
   - CLI prototype implemented (command structure validated)

3. **Documentation**
   - README.md with overview and status
   - SPECIFICATION.md with complete technical design
   - IMPLEMENTATION_PLAN.md with phased roadmap
   - ARCHITECTURE.md with algorithms and data flows
   - PROTOTYPE.md with CLI validation results
   - NEXT_SESSION.md (this file)

4. **CLI Prototype**
   - All commands structured with Commander.js
   - Help text working
   - Argument parsing validated
   - Ready for real implementation

### ❌ Not Yet Implemented
- Database layer (SQLite)
- Actual storage/retrieval logic
- Search algorithms (LIKE, FTS5, fuzzy)
- Tests
- Agent guide documentation

## What to Do Next

### Immediate Next Step: Phase 1 - MVP

**Goal:** Working memory system with basic LIKE search in 2-3 days

**Start with Step 1.2:** Database Layer - Schema & Connection  
**Location:** IMPLEMENTATION_PLAN.md - Phase 1, Step 1.2

### Step-by-Step

1. **Review Documents** (15 minutes)
   ```bash
   cd llmemory
   cat README.md              # Overview
   cat SPECIFICATION.md       # Technical spec
   cat IMPLEMENTATION_PLAN.md # Next steps with checkboxes
   cat docs/ARCHITECTURE.md   # Algorithms and design
   ```

2. **Install Dependencies** (5 minutes)
   ```bash
   npm install
   # Should install: better-sqlite3, commander, chalk, date-fns, vitest
   ```

3. **Test Prototype** (5 minutes)
   ```bash
   node src/cli.js --help
   node src/cli.js store "test" --tags demo
   # Should show placeholder output
   ```

4. **Create Database Layer** (2 hours)
   ```bash
   # Create these files:
   mkdir -p src/db
   touch src/db/connection.js  # Database connection & initialization
   touch src/db/schema.js      # Phase 1 schema definition
   touch src/db/queries.js     # Prepared statements
   ```

   **Implementation checklist:**
   - [ ] SQLite connection with WAL mode
   - [ ] Schema creation (memories, tags, memory_tags)
   - [ ] Indexes on created_at, expires_at, tags
   - [ ] Metadata table with schema_version
   - [ ] Prepared statements for CRUD operations
   - [ ] Transaction helpers

   **Reference:** SPECIFICATION.md - "Data Schema" section  
   **SQL Schema:** IMPLEMENTATION_PLAN.md - Phase 1, Step 1.2

5. **Implement Store Command** (2 hours)
   ```bash
   mkdir -p src/commands src/utils
   touch src/commands/store.js
   touch src/utils/validation.js
   touch src/utils/tags.js
   ```

   **Implementation checklist:**
   - [ ] Content validation (length < 10KB)
   - [ ] Tag parsing (comma-separated, normalize to lowercase)
   - [ ] Expiration date parsing
   - [ ] Insert memory into DB
   - [ ] Insert/link tags (get-or-create)
   - [ ] Return memory ID with success message

   **Reference:** SPECIFICATION.md - "Memory Format Guidelines"

6. **Implement Search Command** (3 hours)
   ```bash
   mkdir -p src/search
   touch src/commands/search.js
   touch src/search/like.js
   touch src/utils/formatting.js
   ```

   **Implementation checklist:**
   - [ ] Build LIKE query with wildcards
   - [ ] Tag filtering (AND logic)
   - [ ] Date filtering (after/before)
   - [ ] Agent filtering (entered_by)
   - [ ] Exclude expired memories
   - [ ] Order by created_at DESC
   - [ ] Format output (plain text with colors)

   **Reference:** ARCHITECTURE.md - "Phase 1: LIKE Search" algorithm

7. **Continue with Steps 1.5-1.8**
   See IMPLEMENTATION_PLAN.md for:
   - List command
   - Prune command
   - CLI integration (replace placeholders)
   - Testing

## Key Files Reference

### Planning & Specification
- `SPECIFICATION.md` - **Start here** for technical design
- `IMPLEMENTATION_PLAN.md` - **Your checklist** for step-by-step tasks
- `docs/ARCHITECTURE.md` - Algorithm details and performance targets
- `README.md` - Project overview and status

### Code Structure
- `src/cli.js` - CLI entry point (currently placeholder)
- `src/commands/` - Command implementations (to be created)
- `src/db/` - Database layer (to be created)
- `src/search/` - Search algorithms (to be created)
- `src/utils/` - Utilities (to be created)
- `test/` - Test suite (to be created)

### Important Patterns

**Database Location:**
```javascript
// Default: ~/.config/opencode/memories.db
// Override with: --db flag
```

**Schema Version Tracking:**
```javascript
// metadata table stores current schema version
// Used for migration triggers
```

**Search Evolution:**
```javascript
// Phase 1: LIKE search (simple, <500 memories)
// Phase 2: FTS5 (production, 10K+ memories)
// Phase 3: Fuzzy (typo tolerance, 100K+ memories)
```

## Development Workflow

### Daily Checklist
1. Pull latest changes (if working with others)
2. Run tests: `npm test`
3. Pick next unchecked item in IMPLEMENTATION_PLAN.md
4. Implement feature with TDD (write test first)
5. Update checkboxes in IMPLEMENTATION_PLAN.md
6. Commit with clear message
7. Update CHANGELOG.md (if created)

### Testing
```bash
npm test              # Run all tests
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report
```

### Commit Message Format
```
<type>(<scope>): <subject>

Examples:
feat(db): implement SQLite connection with WAL mode
feat(store): add content validation and tag parsing
test(search): add integration tests for LIKE search
docs(spec): clarify fuzzy matching threshold
```

## Common Questions

### Q: Which search algorithm should I start with?
**A:** Start with LIKE search (Phase 1). It's simple and sufficient for <500 memories. Migrate to FTS5 when needed.

### Q: Where should the database be stored?
**A:** `~/.config/opencode/memories.db` by default. Override with `--db` flag.

### Q: How do I handle expiration?
**A:** Always filter `WHERE expires_at IS NULL OR expires_at > now()` in queries. Manual cleanup with `memory prune`.

### Q: What about fuzzy matching?
**A:** Skip for Phase 1. Implement in Phase 3 after FTS5 is working.

### Q: Should I use TypeScript?
**A:** Optional. JavaScript is fine for now. TypeScript can be added later if needed.

### Q: How do I test without a real database?
**A:** Use `:memory:` SQLite database for tests. Fast and isolated.

## Performance Targets

| Phase | Dataset | Latency | Storage |
|-------|---------|---------|---------|
| 1 (MVP) | <500 | <50ms | Base |
| 2 (FTS5) | 10K | <100ms | +30% |
| 3 (Fuzzy) | 100K+ | <200ms | +200% |

## Troubleshooting

**Problem:** `better-sqlite3` won't install  
**Solution:** Ensure build tools installed: `sudo apt install build-essential python3`

**Problem:** Database locked  
**Solution:** Enable WAL mode: `PRAGMA journal_mode = WAL;`

**Problem:** Tests failing  
**Solution:** Use `:memory:` database for tests, not persistent file

**Problem:** Slow searches  
**Solution:** Check indexes exist: `sqlite3 memories.db ".schema"`

## Success Criteria for Phase 1

- [ ] Can store memories with tags and expiration
- [ ] Can search with basic LIKE matching
- [ ] Can list recent memories
- [ ] Can prune expired memories
- [ ] All tests passing (>80% coverage)
- [ ] Query latency <50ms for 500 memories
- [ ] Help text comprehensive
- [ ] CLI works end-to-end

**Validation Test:**
```bash
memory store "Docker Compose uses bridge networks by default" --tags docker,networking
memory store "Kubernetes pods share network namespace" --tags kubernetes,networking
memory search "networking" --tags docker
# Should return only Docker memory
memory list --limit 10
# Should show both memories
memory stats
# Should show 2 memories, 3 unique tags
```

## Resources

- **SQLite FTS5:** https://www.sqlite.org/fts5.html
- **better-sqlite3:** https://github.com/WiseLibs/better-sqlite3
- **Commander.js:** https://github.com/tj/commander.js
- **Vitest:** https://vitest.dev/

## Contact/Context

**Project Location:** `/home/nate/nixos/shared/linked-dotfiles/opencode/llmemory/`  
**OpenCode Context:** This is a plugin for the OpenCode agent system  
**Session Context:** Planning done by two investigate agents (see agent reports in SPECIFICATION.md)

## Final Notes

**This project is well-documented and ready to implement.**

Everything you need is in:
1. **SPECIFICATION.md** - What to build
2. **IMPLEMENTATION_PLAN.md** - How to build it (step-by-step)
3. **ARCHITECTURE.md** - Why it's designed this way

Start with IMPLEMENTATION_PLAN.md Phase 1, Step 1.2 and follow the checkboxes!

Good luck! 🚀

---

**Created:** 2025-10-29  
**Phase 0 Status:** ✅ Complete  
**Next Phase:** Phase 1 - MVP Implementation  
**Time Estimate:** 12-15 hours to working MVP