307 lines
9.1 KiB
Markdown
307 lines
9.1 KiB
Markdown
# 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
|