148 lines
4.0 KiB
Markdown
148 lines
4.0 KiB
Markdown
# LLMemory Deployment Guide
|
|
|
|
## Current Status: Phase 1 Complete ✅
|
|
|
|
**Date:** 2025-10-29
|
|
**Version:** 0.1.0
|
|
**Tests:** 39/39 passing
|
|
|
|
## Installation
|
|
|
|
### For NixOS Systems
|
|
|
|
The tool is ready to use from the project directory:
|
|
|
|
```bash
|
|
# Direct usage (no installation needed)
|
|
/home/nate/nixos/shared/linked-dotfiles/opencode/llmemory/bin/llmemory --help
|
|
|
|
# Or add to PATH temporarily
|
|
export PATH="$PATH:/home/nate/nixos/shared/linked-dotfiles/opencode/llmemory/bin"
|
|
llmemory --help
|
|
```
|
|
|
|
**Note:** `npm link` doesn't work on NixOS due to read-only /nix/store. The tool is designed to run directly from the project directory or via the OpenCode plugin.
|
|
|
|
### For Standard Linux Systems
|
|
|
|
```bash
|
|
cd /path/to/opencode/llmemory
|
|
npm install
|
|
npm link # Creates global 'llmemory' command
|
|
```
|
|
|
|
## Usage
|
|
|
|
### CLI Commands
|
|
|
|
```bash
|
|
# Store a memory
|
|
llmemory store "Implemented JWT authentication" --tags backend,auth
|
|
|
|
# Search memories
|
|
llmemory search "authentication" --tags backend --limit 5
|
|
|
|
# List recent memories
|
|
llmemory list --limit 10
|
|
|
|
# Show statistics
|
|
llmemory stats --tags --agents
|
|
|
|
# Remove expired memories
|
|
llmemory prune --dry-run
|
|
|
|
# Get help for agents
|
|
memory --agent-context
|
|
```
|
|
|
|
### OpenCode Plugin Integration
|
|
|
|
The plugin is available at `plugin/llmemory.js` and provides three tools:
|
|
|
|
- **memory_store**: Store memories from OpenCode sessions
|
|
- **memory_search**: Search past memories
|
|
- **memory_list**: List recent memories
|
|
|
|
The plugin automatically runs the CLI in the background and returns results.
|
|
|
|
## Database Location
|
|
|
|
Memories are stored in:
|
|
```
|
|
~/.config/opencode/memories.db
|
|
```
|
|
|
|
The database uses SQLite with WAL mode for better concurrency.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
llmemory/
|
|
├── bin/llmemory # Executable shim (node bin/llmemory)
|
|
├── src/
|
|
│ ├── cli.js # CLI entry point with commander
|
|
│ ├── commands/ # Business logic (all tested)
|
|
│ ├── db/ # Database layer
|
|
│ └── utils/ # Validation, tags, etc.
|
|
├── plugin/ # OpenCode integration (in parent dir)
|
|
└── test/ # Integration tests (39 passing)
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Watch mode
|
|
npm run test:watch
|
|
|
|
# Manual testing
|
|
node src/cli.js store "Test memory" --tags test
|
|
node src/cli.js search "test"
|
|
node src/cli.js list --limit 5
|
|
```
|
|
|
|
## NixOS-Specific Notes
|
|
|
|
1. **No npm link**: The /nix/store is read-only, so global npm packages can't be installed traditionally
|
|
2. **Direct execution**: Use the bin/llmemory shim directly or add to PATH
|
|
3. **Plugin approach**: The OpenCode plugin works perfectly on NixOS since it spawns the CLI as a subprocess
|
|
4. **Database location**: Uses XDG_CONFIG_HOME if set, otherwise ~/.config/opencode/
|
|
|
|
## OpenCode Integration Status
|
|
|
|
✅ **Plugin Created**: `plugin/llmemory.js`
|
|
✅ **Tools Defined**: memory_store, memory_search, memory_list
|
|
✅ **CLI Tested**: All commands working with colored output
|
|
✅ **JSON Output**: Supports --json flag for plugin parsing
|
|
|
|
## Next Steps for Full Integration
|
|
|
|
1. **Test plugin in OpenCode session**: Load and verify tools appear
|
|
2. **Add to agent documentation**: Update CLAUDE.md or similar with memory tool usage
|
|
3. **Consider auto-storage**: Hook into session end to auto-store context
|
|
4. **Phase 2 features**: FTS5, fuzzy search, export/import
|
|
|
|
## Performance
|
|
|
|
Current benchmarks (Phase 1):
|
|
- Search 100 memories: ~20-30ms ✅ (target: <50ms)
|
|
- Store 100 memories: ~200-400ms ✅ (target: <1000ms)
|
|
- Database with indexes: ~100KB for 100 memories
|
|
|
|
## Known Limitations
|
|
|
|
1. **npm link doesn't work on NixOS** - Use direct execution or plugin
|
|
2. **Export/import not yet implemented** - Coming in Phase 2
|
|
3. **No fuzzy search yet** - LIKE search only (Phase 3 feature)
|
|
4. **Manual cleanup required** - Use `llmemory prune` to remove expired memories
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
- Check SPECIFICATION.md for technical details
|
|
- See ARCHITECTURE.md for system design
|
|
- Review test/integration.test.js for usage examples
|
|
- Read TESTING.md for TDD philosophy
|