feat(memory): FTS5 + embedding semantic search over session history

[TerrysPOV]

Background

ClaudeClaw-Plus has a persistent memory system. A complementary layer — searchable session history — would give Claude recall over past work without loading entire sessions into context.

Proposed approach (from @Nibbler1250)

Index all session JSONL files into SQLite with two search layers:

1. FTS5 — fast exact keyword match
2. Sentence-transformer vectors — semantic similarity (all-MiniLM-L6-v2, ~80MB)

Combined weighted hybrid score: alpha * vector_score + (1-alpha) * fts5_score

For Claude Max users (no separate API key), summaries can pipe through the claude --print CLI rather than the SDK:

result = subprocess.run(
    ["claude", "--print", "--model", "claude-haiku-4-5"],
    input=summary_prompt, capture_output=True, text=True
)

@Nibbler1250 has a working ~200-line Python implementation ready to contribute.

Why ClaudeClaw-Plus

• Orthogonal to (but complementary with) Plus's existing MEMORY.md system
• Provides unlimited searchable history without blowing up context window
• The infrastructure complexity (SQLite, embeddings) fits Plus's scope

Source

Requested by @Nibbler1250 in moazbuilds/claudeclaw#14 (Mega-Post) with a working proof-of-concept.

[Nibbler1250]

Thanks for picking this up @TerrysPOV — happy to drive the PR.

Quick alignment questions before I open it:

1. Placement — should this live as:

   • (a) standalone Python tool in scripts/ or tools/session-search/ (current shape — pure Python, ~200 lines, owns its SQLite db), invoked via CLI from skills?
   • (b) TS module in src/memory-search/ that shells out to the Python implementation (cleanest from Plus's perspective, but adds an indirection)?
   • (c) Replacement/extension to src/memory.ts (would be a bigger refactor — memory.ts is currently single-file MEMORY.md, this would change its responsibility)?

   My instinct says (a) — keep it as a Python tool that any skill can invoke, leave memory.ts untouched. Plus is mostly TS but has prompts/ and other non-TS resources, so a Python tool fits.

2. Indexing trigger — should the indexer run:

   • On daemon boot (one-shot reindex of new sessions)?
   • As a periodic job (cron-style every N hours)?
   • On-demand only via skill invocation?

   I currently run it ad-hoc + nightly cron. Open to your preference.

3. Embeddings model — all-MiniLM-L6-v2 (~80MB on disk, 384-dim) is my default. Plus's runner already pulls model files in some configs, so no new install pattern needed. Want me to make the model configurable, or pin this default?

4. Scope — should the first PR include:

   • Just the indexer + search lib (Python),
   • Plus the skill (skills/session-recall.md) so it's plug-and-play after install,
   • Plus integration into the agent system prompt (so Claude proactively uses recall)?

   I'd suggest the first two for the initial PR, leave (3) for a follow-up since it touches agents.ts and prompts/.

Will start refactoring my local code to drop the hardcoded /home/simon/agent/ paths and use PROJECT_DIR / CLAUDECLAW_DIR like the rest of Plus. Aiming to open the PR within a day or two.

Also — really appreciate the framing here. The #7 'heavy work goes here' line + you opening a dedicated tracking issue makes contributing way more rewarding than dropping PRs blind.

[TerrysPOV]

1. c I know it is more work, but I genuinely feel this is an improvement on the current pattern and so long as we cn retain the deterministic read/write patterns then this is my favoured approach.

2. On daemon boot (one-shot reindex of new sessions) and as a periodic job (I suggest after n number of turns which is configurable default = 10)

3. Configurable but defaulted to all-MiniLM-L6-v2

4. Agreed

Glad you like the approach. Upstream is a fantastic base to build from for a more complex, feature risk and enterprise grade product.

[Nibbler1250]

Got it, going with option (c) — integrate into src/memory.ts as an extension that preserves the deterministic read/write semantics. The Python implementation stays as the indexer/searcher under the hood (handles SQLite + sentence-transformers); src/memory.ts grows two new entry points (indexSessions(), searchSessions()) that shell out and return cleanly typed results.

Concrete plan based on your answers:

• tools/memory-search/ (Python, ~700 lines) — unchanged, just the deterministic indexer/searcher CLI.
• src/memory.ts — adds:
  • indexSessions(opts?) — spawns the Python indexer, returns counts.
  • searchSessions(query, opts) — spawns the Python search CLI, returns parsed JSON hits.
  • Reads remain synchronous-feeling and return current on-disk state every call (no in-process cache).
• Boot trigger — wire into src/commands/start.ts so the daemon kicks off a one-shot incremental index on startup.
• Per-turn trigger — hook into the runner with a configurable memorySearch.reindexEveryNTurns setting (default 10). Configurable via Plus's settings.json so users can crank it up or off.
• Embedding model name configurable via env / settings, defaulting to all-MiniLM-L6-v2.
• First PR scope: indexer + skill (no agents.ts integration yet — saving that for a follow-up so it stays small and reviewable).

Already pushed a working Python core to my fork (Nibbler1250/ClaudeClaw-Plus:feat/memory-search) with tests passing on 41 sessions / 427 chunks. Now adapting the TS wrapper. Will open the PR (draft first, you can review the shape, then I'll mark ready for review) within the next few hours.

Cheers.