nixos/shared/linked-dotfiles/opencode/llmemory/NEXT_SESSION.md

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)

   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)

   npm install
   # Should install: better-sqlite3, commander, chalk, date-fns, vitest
   

3. Test Prototype (5 minutes)

   node src/cli.js --help
   node src/cli.js store "test" --tags demo
   # Should show placeholder output
   

4. Create Database Layer (2 hours)

   # 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)

   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)

   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:

// Default: ~/.config/opencode/memories.db
// Override with: --db flag

Schema Version Tracking:

// metadata table stores current schema version
// Used for migration triggers

Search Evolution:

// 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

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:

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