---

Description: Implementation plan and priority improvements

Current Status: v0.4.0 In Development

Release v0.4.0 (2025-11-25) includes:

• ✅ HiRAG Phase 2 (Automatic LLM-based summarization, multi-hop retrieval)
• ✅ Cross-device sync backends (Firebase/WebSocket integration)
• ✅ Re-ranking strategies (BM25, MMR, Diversity, Recency)
• ✅ Advanced retrieval methods

Completed Sprint: HiRAG Phase 2 & Advanced Retrieval

HiRAG Phase 2 - COMPLETED ✅

1. Automatic Summarization ✅

   • Integrate LLM-based automatic summarization via LLMAdapter interface
   • Configurable prompt templates for custom summarization
   • Automatic relationship creation (summary_of and part_of)
   • Layer-based aggregation and node grouping

2. Multi-Hop Retrieval ✅

   • Layer-aware semantic search with context enrichment
   • Configurable search depth (maxHops parameter)
   • Hierarchical traversal following summary_of relationships
   • Result enrichment with parent context nodes

3. Advanced Relationships ✅

   • Support for summary_of and part_of relation types
   • Bidirectional relationship traversal
   • Integration with multi-hop search

Cross-Device Sync - COMPLETED ✅

1. Backend Abstraction ✅

   • SyncBackend interface for pluggable backends
   • Factory pattern for backend selection
   • Stream-based real-time synchronization

2. Firebase Backend ✅

   • Firebase Realtime Database integration
   • Anonymous and API key authentication
   • Encrypted snapshot publishing
   • Real-time change subscriptions

3. WebSocket Backend ✅

   • Custom WebSocket server integration
   • Heartbeat/keep-alive mechanism
   • Bidirectional synchronization
   • Automatic fallback from Firebase

4. Sync Management ✅

   • CrossDeviceSyncManager extending SyncManager
   • Automatic backend initialization
   • LWW (Last-Write-Wins) conflict resolution
   • Encrypted snapshot merge

Re-ranking & Advanced Retrieval - COMPLETED ✅

1. Re-ranking Strategies ✅

   • ReRankingStrategy interface
   • BM25 re-ranker (term frequency-based)
   • MMR re-ranker (Maximal Marginal Relevance)
   • Diversity re-ranker (maximize variety)
   • Recency re-ranker (favor recent nodes)

2. Integration ✅

   • semanticSearchWithReRanking() in MemoryGraph
   • hybridSearchWithReRanking() in MemoryGraph
   • Flexible re-ranker composition

3. Testing ✅

   • Unit tests for all re-ranking strategies
   • Integration tests for HiRAG Phase 2
   • Sync conflict resolution tests
   • Multi-hop retrieval tests

Next Sprint: Production Hardening & Performance

Priority Tasks

1. Performance Optimization

   • Implement caching for multi-hop search intermediate results
   • Optimize BM25 IDF calculation with memoization
   • Add batch operations for large-scale summarization
   • Profile and optimize vector search performance

2. Production Sync Server

   • Reference WebSocket server implementation
   • Docker deployment configuration
   • Load balancing and scaling guidelines
   • Monitoring and health checks

3. Enhanced Testing

   • Generate mocks for WebSocket tests (build_runner)
   • Increase test coverage to >80%
   • Add integration tests for Firebase backend
   • Performance benchmarks for re-ranking strategies

4. Documentation

   • Migration guide from v0.3.0 to v0.4.0
   • Best practices for LLM adapter implementation
   • Sync backend deployment guide
   • Performance tuning recommendations

Technical Tasks

1. On-Device Backend Selection

   • Evaluate tflite_flutter vs onnxruntime (Selected onnxruntime).
   • Choose a base model (e.g., MiniLM/E5-small) and prepare export (ONNX/TFLite) + INT8 quantization.

2. Adapter and Utilities

   • Create OnDeviceEmbeddingsAdapter with lazy initialization.
   • Implement WordPiece tokenizer (WordPieceTokenizer).
   • Handle versions/dimensions per namespace and optional L2 normalization.
   • Telemetry: p50/p95 latencies, peak memory, errors.

3. Resource Investigation (Document in README)

   • Document model download and usage instructions.
   • Model size (fp32 vs INT8) and RAM required during inference (model + buffers).
   • Storage cost for N vectors (fp32 vs INT8) and approximate HNSW overhead.
   • Device/ABI limits (armeabi-v7a, arm64-v8a) and split-ABI policies.

4. Multi-App Synchronization (Design)

   • Client-side encryption (user key), versioning, reconciliation (LWW/CRDT), and semantic deduplication.
   • Background synchronization of embeddings and metadata with quotas/thresholds.

5. Benchmarks and Quality

   • Microbenchmarks for embed/search (latency and throughput) via GitHub Actions.
   • Stress and concurrency tests (ingestion + simultaneous search).

6. Hybrid and Re-rank (Phase 2)

   • Add BM25/FTS (Isar Filter) for recall and fusion (RRF/Weighted).
   • Compact on-device re-ranker over top-K results.

Deliverables

• Functional on-device adapter + usage example.
• Benchmark automation (GitHub Actions).
• Sync Protocol Design Document (doc/SYNC_PROTOCOL.md).
• Semantic Deduplication logic.
• Hybrid Search implementation.
• HiRAG Phase 1 (Layer-based organization, summary nodes, basic queries).

Completed Releases

Release 0.3.0 (2024-11-24) ✅

Major Features:

• Sync Protocol with AES-256-GCM encryption and LWW conflict resolution
• HiRAG Phase 1: Hierarchical knowledge organization
• Extended data models with UUID-based sync fields
• Integration tests for sync functionality

Deliverables:

• SyncManager with encrypted export/import
• EncryptionService for client-side encryption
• HierarchicalMemoryGraph extension
• Layer-based node organization
• Summary node creation and queries
• Documentation: doc/SYNC_PROTOCOL.md
• Published to pub.dev

---

Historical Research Notes

• Model Memory:
  • MiniLM/E5-small fp32: ~60–90 MB; INT8: ~15–25 MB.
  • onnxruntime AAR: ~7–12 MB (depending on EPs); tflite_flutter: ~2–3 MB.
• Inference RAM:
  • Peak ≈ model size + intermediate buffers (1.2–2.0× model size) per batch.
  • Small batch size (1–8) recommended for mid-range devices; measure p50/p95.
• Index Storage:
  • Vectors: N × d × bytes (fp32: 4B, int8: 1B). Example: 50k × 384 × 4 ≈ 76.8 MB; int8 ≈ 19.2 MB.
  • HNSW overhead approx: ~N × M × 8B (M≈16 default → ~6.4 MB for 50k).
• Compatibility/ABIs:
  • Android: arm64-v8a (recommended), armeabi-v7a (limited). Use split-ABI to reduce APK size.
  • Accelerators: NNAPI (variable by OEM), universal CPU fallback.
• Synchronization (Multi-App):
  • Client encryption (user key), LWW/CRDT versioning, semantic deduplication.
  • Upload only metadata + embeddings (possibly int8) with quotas and incremental sync.
  • Optional: ObjectBox Sync if near-real-time and minimal conflict resolution is required.

---

Release 0.2.3 (Upcoming)

• New features: Hybrid Search, Semantic Deduplication.
• Tools: Benchmarking script and workflow.
• Documentation: Sync Protocol Design.

---

Release 0.2.3 (Completed - 2024-11-24)

• Fix critical bugs from 0.2.2
• Update CHANGELOG.md with all fixes
• Optimize package size (exclude test_resources/ and tool/)
• Update workflow to use Flutter instead of Dart
• Create tag/release (v0.2.3)
• Publish to pub.dev (isar_agent_memory 0.2.3)

Release 0.2.2 (Completed - 2025-08-18)

• Clean repo binaries/artifacts: .dart_tool/, isar.dll, example/isar.dll, *db/, isar_agent_memory_tests/testdb/.
• Confirm pubspec.yaml version 0.2.2 and updated CHANGELOG.md.
• Implement OnDeviceEmbeddingsAdapter using ONNX Runtime.
• Execute manual workflow .github/workflows/publish-to-pub-dev.yml on main.
• Verify publication on pub.dev (isar_agent_memory 0.2.2).
• Create tag/release (v0.2.2).

---

Completed Tasks (Summary)

• Pluggable Vector Backend (VectorIndex) and ObjectBoxVectorIndex as default.
• Embeddings Fallback (Gemini) and FallbackEmbeddingsAdapter.
• InMemoryVectorIndex for tests (no natives), cosine/L2/dot metrics.
• DVDB sanitization (code, docs, tests) and updated README/TASKS.
• Version bump 0.2.0, flat_buffers and reinforced .pubignore.
• Update dependencies to latest stable versions (LangChain 0.8.0, ObjectBox 5.0.0).
• Translate documentation to English.
• Implement On-Device Embeddings with ONNX Runtime.