Stub-text

Memory stub-systemet: semantisk retrieval av arkiverade minnessektioner. Skill memory-stubs (db.js, archive-section.js, refresh-stub.js, refresh-all-channels.js), per-kanal stubs.db, runtime-hook i data/sessions/{kanal}/agent-runner-src/memory-stubs.ts injicerar matchande arkivfiler vid varje user-message. Embeddings via gemini-embedding-001 (3072 dim). Cosine similarity match mot SIMILARITY_THRESHOLD (0.6) och MIN_MARGIN_TO_RUNNERUP (0.05).

Läs vid frågor om:
- Hur stubs fungerar, embeddings, runtime-hook, retrieval-systemet
- Debug av stub-matchning, varför stubs triggas eller inte triggas, varför vissa stubs över-matchar
- Telemetri (match_count, last_matched_at), refresh-frekvens (nattjobb 03:20 UTC)
- Hur man skapar/ändrar/raderar stubs, archive_path-konvention, refresh_source-fält
- När stubs ska skrivas om, embedding-similarity-tröskel, token-budget
- Varför subagenter inte ärver stub-injection, container vs host paths
- CLI-verktyg, archive-section.js, manuell INSERT med embedding

Fullständigt arkiv

Memory stub-systemet

Senast uppdaterad: 2026-05-04

Semantisk retrieval av arkiverade minnessektioner. Håller memory.md kort genom att flytta detaljer till arkivfiler som bara injiceras när användarens fråga matchar.

Arkitektur (i tre lager)

1. Skill: memory-stubs (/workspace/extra/server/nanoclaw/groups/global/skills/memory-stubs/)
• db.js: schema, init, insert, getAll, telemetri, cosineSimilarity
• embedding-client.js: Gemini gemini-embedding-001 med SHA256-cache + retry-backoff
• archive-section.js: CLI för manuell arkivering av en sektion ur memory.md
• refresh-stub.js: refreshar enskild stub baserat på archive_path-innehåll
• refresh-all-channels.js: nattjobbet som kör refresh-stub över alla kanaler 03:20 UTC

1. Lagring: per-kanal sqlite-db
• Sökväg: /workspace/project/groups/{kanal}/memory/stubs.db (container) = /workspace/extra/server/nanoclaw/groups/{kanal}/memory/stubs.db (host)
• Globalt fallback: /workspace/project/groups/shared/memory/stubs-global.db (om finns)
• Schema:

`` id INTEGER PRIMARY KEY title TEXT stub_text TEXT -- kort hook som embeddas archive_path TEXT -- absolut path till .md-fil med fullt innehåll embedding BLOB -- Float32Array little-endian (3072 dim * 4 bytes = 12288 B) created_at TEXT last_matched_at TEXT match_count INTEGER refresh_source TEXT -- JSON: {"type":"file-watch","path":"..."} eller scheduler-db-query / script / manual last_refreshed_at TEXT ``

1. Runtime-hook: memory-stubs.ts (data/sessions/{kanal}/agent-runner-src/memory-stubs.ts)
• Körs vid varje inkommande user-message
• Genererar embedding för meddelandet
• Cosinussimilarity mot alla stubs (kanal + global)
• Filtrerar på SIMILARITY_THRESHOLD, plockar top N inom token-budget
• Läser archive_path-filerna och injicerar deras innehåll som <system-context>-block i systemprompten innan agenten startar
• Bumpar match_count + last_matched_at per matchad stub
• Felhantering: alla fel sväljs så agenten aldrig kraschar

Hela flödet (vid varje user-message)

1. User skriver i Discord/Telegram/WhatsApp
2. Agent-runner anropar memory-stubs.ts
3. Embedding-genering via Gemini (cached på SHA256)
4. Cosinus mot alla stubs i kanalens stubs.db (+ global)
5. Top-N stubs över threshold, läs archive_path-innehåll
6. Injicera som "Relevant arkiverat material"-sektion i systemprompt
7. Claude-tur startar med stubs som extra kontext
8. match_count bumpas

Viktiga regler

• Subagenter ärver INTE stub-injection. Bara main-runtime kör hooken. Om en subagent behöver kontext från en stub måste main-runtime passera det manuellt i prompten.
• archive_path skrivs som container-path (/workspace/project/...) eftersom hooken läser via container-mount.
• refresh_source MÅSTE sättas för att nattjobbet ska refresha stubben. Värdet NULL hoppas över. Vanliga typer: file-watch (peka på .md-fil), scheduler-db-query (SQL-query mot scheduler-db), script (kör custom script), manual (refreshas aldrig).
• Embedding-modell: gemini-embedding-001 (3072 dim). Måste matcha mellan write-time och read-time, annars matchar inget.
• Skapa stubs när: memory.md växer förbi ~15-20k chars, eller när en sektion bara är relevant för specifika frågor (tekniska detaljer, kund-fakta, API-quirks).

CLI-verktyg

• Arkivera + skapa stub:

``bash cd /workspace/extra/server/nanoclaw/groups/global/skills/memory-stubs node archive-section.js \ --memory-file /path/to/memory.md \ --section "## Trello API" \ --archive-dir /path/to/memory/archived \ --db-path /path/to/memory/stubs.db \ --stub-text "Trello API-endpoints, board-IDs, veckodagslistor. Läs vid frågor om kort, tasks, boards." ``

• Läs/skriv databasen från container (sqlite3 CLI saknas):

``bash node /workspace/group/sqlite3-wrapper.js --header /path/to/stubs.db "SELECT id, title, refresh_source FROM stubs ORDER BY id" ``

• Manuell INSERT med Gemini-embedding (om archive-section.js inte passar):

Skriv ett kort node-script som hämtar embedding via https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GEMINI_API_KEY, packar floats som little-endian Float32Array Buffer, och INSERTar via better-sqlite3.

Insights och lärdomar

• 2026-05-04: Jag (Andy/Flexbert) trodde först att retrieval-hooken inte fanns och föreslog att bygga den. Den fanns redan i data/sessions/{kanal}/agent-runner-src/memory-stubs.ts. Slutsats: när Jonatan frågar "är det live?" om en feature, kolla ALLTID data/sessions/{kanal}/agent-runner-src/ innan jag säger nej. Det är där runtime-hooks ligger, inte i src/.

• 2026-05-04: Stub-uppdatering på en delad tool-guide (t.ex. groups/shared/tool-guides/bidtheatre-api.md) får INTE ske med Write som skriver över hela filen. Använd Edit och lägg till sektioner. Den filen kan ha auto-appended insights och multi-account-konfig som lätt försvinner.

• 2026-04-25: Refresh-cron 03:20 UTC. Stubs med refresh_source IS NULL skippas tyst. Kolla last_refreshed_at om en stub inte verkar uppdateras.

• 2026-04: Granularitet är en avvägning. Per-fråga: om du frågar om "GTM" och stubben heter "Advanced Matching" får du inte CAPI-kontexten. Lösning: grovstubs som täcker en hel domän hellre än hyper-specifika.

Status per kanal (2026-05-04)

• safariresor: 3 stubs live (Tracking-stack, Mätning+BigQuery, BidTheatre). Refresh_source satt på alla.
• discord-main: 4 stubs live (Schemalagda jobb, SVG Ads Database, OAuth Extra Usage, Matprisjamforare).
• andra kanaler: varierande, kolla per kanal med node sqlite3-wrapper.js {path}/stubs.db "SELECT id, title FROM stubs".

Referenser

• Skiss/design: /workspace/extra/Documents/memory/skiss-stub-system-v3.md (om den finns)
• Skill-README: /workspace/extra/server/nanoclaw/groups/global/skills/memory-stubs/README.md
• Runtime-hook: /workspace/extra/server/nanoclaw/data/sessions/{kanal}/agent-runner-src/memory-stubs.ts