# PROP: Local-First Agent Memory with sqlite-vec + Engram Pattern

## Source
- **URL**: https://github.com/asg017/sqlite-vec (7.1k stars, MIT/Apache-2.0)
- **URL**: https://github.com/Gentleman-Programming/engram (655 stars, Go, MCP)
- **URL**: https://github.com/thedotmack/claude-mem (32.8k stars, AGPL-3.0)
- **Author**: Alex Garcia (sqlite-vec), Gentleman Programming (Engram), thedotmack (claude-mem)
- **Date**: 2024-11 (sqlite-vec v0.1.6), 2026-02 (Engram latest), 2025-12 (claude-mem)

## Summary
sqlite-vec is a zero-dependency C extension for SQLite that adds vector search (brute-force KNN). Combined with sentence-transformers for local embeddings and SQLite FTS5 for keyword search, it provides a complete local-first memory system with zero infrastructure. Engram demonstrates the MCP-based memory pattern (13 tools including mem_save, mem_search, mem_context). claude-mem demonstrates the hooks-based capture pattern.

## Relevance to iEvo
iEvo currently uses plain markdown files for memory (CONTEXT.md, DECISIONS.md, etc.). This works for structured data but fails for semantic retrieval ("find the session where we discussed Docker isolation"). sqlite-vec adds semantic search to the existing SQLite-based storage (REQ-012 already captures trajectories to SQLite). No new infrastructure needed.

## Proposed Change

### Phase 1: Hybrid Memory Store (low effort)
1. Add `sqlite-vec` as a dependency (pip install sqlite-vec).
2. Add `sentence-transformers` with `all-MiniLM-L6-v2` model (384-dim, 80MB, runs on CPU).
3. Create `src/ievo/core/memory.py` with:
   - `MemoryStore` class wrapping SQLite + sqlite-vec + FTS5
   - `save(content, metadata)` -> embeds + stores
   - `search(query, k=5)` -> semantic search via sqlite-vec
   - `search_keyword(query)` -> FTS5 full-text search
   - `search_hybrid(query)` -> combined ranking
4. Integrate with existing debug_capture (REQ-012): trajectory observations auto-indexed.
5. Storage: `.ievo/memory.db` (single file, portable).

### Phase 2: MCP Memory Server (medium effort)
6. Expose memory as MCP server (JSON-RPC 2.0) so any agent can call mem_save/mem_search.
7. Follow Engram's 13-tool pattern but adapted for iEvo's session model.

### Why NOT Mem0/Letta/Zep/Chroma
- **Mem0** (48.7k stars): requires external LLM for extraction (gpt-4.1-nano default). Adds API cost for every memory operation. Overkill for local CLI.
- **Letta** (21.4k stars): requires PostgreSQL + Docker compose. Heavy infrastructure for a CLI tool.
- **Zep**: Community Edition deprecated. Cloud-only going forward.
- **Chroma** (23k stars): good but heavier than sqlite-vec (runs its own server process). sqlite-vec is just a SQLite extension -- zero extra processes.
- **LangMem** (1.3k stars): tight LangGraph coupling, MIT license is good but adds framework dependency.
- **Engram** (655 stars): right pattern but wrong language (Go binary). Learn from it, don't depend on it.

### Winner: sqlite-vec + sentence-transformers
- Zero infrastructure (just a SQLite extension)
- pip install only
- Works offline
- 7.1k stars, Mozilla-backed, dual MIT/Apache-2.0 license
- Already proven with LangChain integration
- Combines naturally with existing SQLite usage (REQ-012 trajectories)

## Affected Components
- New: `src/ievo/core/memory.py`
- New: dependency `sqlite-vec`, `sentence-transformers`
- Modified: debug_capture hooks (auto-index observations)
- Modified: `.ievo/` directory (add memory.db)

## Scores
- Applicability: 5/5
- Effort: low (Phase 1), medium (Phase 2)
- Impact: quality, speed, reliability
