@poolzin/pool-bot 2026.3.9 → 2026.3.10

package/docs/features/advanced-memory.md

@@ -0,0 +1,585 @@
+# Advanced Memory System
+
+PoolBot features a sophisticated memory system for context-aware conversations, supporting semantic search, keyword search, and hybrid retrieval strategies.
+
+## Overview
+
+The memory system provides:
+
+- **Semantic Search** - Find relevant context using vector embeddings
+- **Keyword Search** - Traditional FTS (Full Text Search) using SQLite FTS5
+- **Hybrid Search** - Combine semantic + keyword for best results
+- **MMR (Maximal Marginal Relevance)** - Diverse results, avoiding redundancy
+- **Temporal Decay** - Prioritize recent memories
+
+## Architecture
+
+```
+User Query
+    │
+    ▼
+┌─────────────────────────────────────┐
+│         Memory Manager              │
+│  ┌──────────┐    ┌──────────────┐  │
+│  │ Keyword  │    │   Semantic   │  │
+│  │  Search  │    │    Search    │  │
+│  │  (FTS5)  │    │ (Embeddings) │  │
+│  └────┬─────┘    └──────┬───────┘  │
+│       │                  │         │
+│       └────────┬─────────┘         │
+│                ▼                   │
+│         ┌─────────────┐            │
+│         │Hybrid Merge │            │
+│         │+ MMR + Time │            │
+│         └──────┬──────┘            │
+└────────────────┼───────────────────┘
+                 ▼
+          Relevant Memories
+```
+
+## Configuration
+
+### Basic Setup
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "enabled": true,
+        "provider": "openai",
+        "fallback": "ollama"
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable memory search |
+| `provider` | string | `"openai"` | Primary embedding provider |
+| `fallback` | string | - | Fallback provider if primary fails |
+| `sources` | array | `["memory"]` | Memory sources to search |
+| `extraPaths` | array | `[]` | Additional paths to index |
+
+### Query Configuration
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "query": {
+          "maxResults": 10,
+          "minScore": 0.5,
+          "hybrid": {
+            "enabled": true,
+            "vectorWeight": 0.7,
+            "textWeight": 0.3,
+            "candidateMultiplier": 4,
+            "mmr": {
+              "enabled": true,
+              "lambda": 0.5
+            },
+            "temporalDecay": {
+              "enabled": true,
+              "halfLifeDays": 30
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Search Modes
+
+### Hybrid Search (Default)
+
+Combines keyword and semantic search with configurable weights:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "query": {
+          "hybrid": {
+            "enabled": true,
+            "vectorWeight": 0.7,
+            "textWeight": 0.3
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**How it works:**
+1. Performs both keyword (FTS5) and semantic (vector) searches
+2. Merges results with weighted scoring
+3. Applies MMR reranking for diversity
+4. Applies temporal decay boost
+
+### Keyword-Only Search
+
+For exact term matching without API calls:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "query": {
+          "hybrid": {
+            "enabled": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Best for:**
+- Offline operation
+- Exact term matching
+- Proper nouns and IDs
+
+## Embedding Providers
+
+### OpenAI (Recommended)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "provider": "openai",
+        "remote": {
+          "baseUrl": "https://api.openai.com/v1",
+          "apiKey": "${OPENAI_API_KEY}"
+        }
+      }
+    }
+  }
+}
+```
+
+### Ollama (Local)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "provider": "ollama",
+        "remote": {
+          "baseUrl": "http://localhost:11434"
+        },
+        "local": {
+          "modelPath": "nomic-embed-text"
+        }
+      }
+    }
+  }
+}
+```
+
+### Gemini
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "provider": "gemini",
+        "remote": {
+          "apiKey": "${GEMINI_API_KEY}"
+        }
+      }
+    }
+  }
+}
+```
+
+## MMR (Maximal Marginal Relevance)
+
+MMR ensures diverse results, avoiding redundancy:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "query": {
+          "hybrid": {
+            "mmr": {
+              "enabled": true,
+              "lambda": 0.5
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| Parameter | Description | Range |
+|-----------|-------------|-------|
+| `lambda` | Balance relevance vs diversity | 0-1 (0.5 = balanced) |
+
+**Example:**
+
+Without MMR:
+```
+1. "JavaScript arrays methods"
+2. "JavaScript arrays tutorial"
+3. "JavaScript arrays guide"
+```
+
+With MMR (λ=0.5):
+```
+1. "JavaScript arrays methods"
+2. "Python list comprehensions"
+3. "Rust vectors overview"
+```
+
+## Temporal Decay
+
+Prioritize recent memories:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "query": {
+          "hybrid": {
+            "temporalDecay": {
+              "enabled": true,
+              "halfLifeDays": 30
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `halfLifeDays` | Days for relevance to decay by 50% | 30 |
+
+**Decay Formula:**
+```
+score = baseScore * (0.5 ^ (daysAgo / halfLifeDays))
+```
+
+## Memory Sources
+
+### Default Memory
+
+Files in the `memory/` directory are automatically indexed:
+
+```
+memory/
+├── snippets/
+│   └── javascript/
+│       └── array-methods.md
+├── docs/
+│   └── architecture.md
+└── decisions/
+    └── adr-001.md
+```
+
+### Extra Paths
+
+Add additional paths to index:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "extraPaths": [
+          "~/notes/**/*.md",
+          "docs/**/*.md"
+        ]
+      }
+    }
+  }
+}
+```
+
+### Session Memory
+
+Recent conversation history can be included:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "experimental": {
+          "sessionMemory": true
+        }
+      }
+    }
+  }
+}
+```
+
+## Indexing
+
+### Automatic Indexing
+
+Memories are indexed automatically on:
+- Gateway startup (if `sync.onSessionStart` is enabled)
+- File changes in memory directories (if `sync.watch` is enabled)
+- Before search (if `sync.onSearch` is enabled - lazy mode)
+
+### Sync Configuration
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "sync": {
+          "onSessionStart": true,
+          "onSearch": false,
+          "watch": true,
+          "watchDebounceMs": 5000
+        }
+      }
+    }
+  }
+}
+```
+
+### Session Sync
+
+Control how session history is indexed:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "sync": {
+          "sessions": {
+            "deltaBytes": 100000,
+            "deltaMessages": 10
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Storage
+
+### Vector Index
+
+SQLite with vector extension for embeddings:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "store": {
+          "path": "~/.poolbot/memory.db",
+          "vector": {
+            "enabled": true,
+            "extensionPath": "~/.poolbot/vector.dylib"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Caching
+
+Cache embedding results to reduce API calls:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "cache": {
+          "enabled": true,
+          "maxEntries": 10000
+        }
+      }
+    }
+  }
+}
+```
+
+## Chunking
+
+Control how documents are split for indexing:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "chunking": {
+          "tokens": 512,
+          "overlap": 50
+        }
+      }
+    }
+  }
+}
+```
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `tokens` | Target chunk size in tokens | 512 |
+| `overlap` | Overlap between chunks in tokens | 50 |
+
+## QMD Integration
+
+PoolBot can use QMD (Query My Documents) as an alternative backend:
+
+```json
+{
+  "memory": {
+    "backend": "qmd",
+    "qmd": {
+      "command": "qmd",
+      "includeDefaultMemory": true,
+      "paths": [
+        { "path": "~/docs", "pattern": "**/*.md" }
+      ],
+      "limits": {
+        "maxResults": 10,
+        "maxSnippetChars": 500,
+        "maxInjectedChars": 4000
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Developer Knowledge Base
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "enabled": true,
+        "sources": ["memory"],
+        "extraPaths": [
+          "snippets/**/*.md",
+          "docs/**/*.md",
+          "decisions/**/*.md"
+        ],
+        "query": {
+          "hybrid": {
+            "mmr": {
+              "enabled": true,
+              "lambda": 0.6
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Project-Specific Memory
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "project-alpha",
+        "memorySearch": {
+          "extraPaths": [
+            "agents/project-alpha/memory/**/*.md",
+            "projects/alpha/docs/**/*.md"
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Cost Optimization
+
+Use local embeddings to reduce API costs:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "memorySearch": {
+        "provider": "ollama",
+        "fallback": "openai",
+        "cache": {
+          "enabled": true,
+          "maxEntries": 50000
+        }
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Search Returns No Results
+
+1. Verify memories exist in indexed paths
+2. Check index is up to date (restart gateway or trigger sync)
+3. Lower `minScore` threshold
+4. Verify embedding provider is working
+
+### Slow Search Performance
+
+1. Enable embedding cache
+2. Use keyword-only mode for simple queries
+3. Reduce `candidateMultiplier`
+4. Check vector extension is loaded
+
+### High API Costs
+
+1. Use local Ollama embeddings
+2. Increase cache size
+3. Enable batch processing
+4. Use keyword-only mode for some queries
+
+### Index Not Updating
+
+1. Check `sync.watch` is enabled
+2. Verify file permissions on memory paths
+3. Check `watchDebounceMs` is not too high
+4. Manually trigger reindex by restarting gateway
+
+## See Also
+
+- [Memory Configuration](../concepts/memory.md)
+- [QMD Integration](../integrations/qmd.md)
+- [Agent Configuration](../agents/configuration.md)