Memory — best path (operator guide)

Memory — best path for Kazma

Recommended way to run V2 cognitive memory + Knowledge Library after the memory program. Do not merge stores into one table. Use a unified chat experience on separate stores.

Deep architecture: Memory & RAG.

Architecture (keep this)

Chat turn
  ├─ Personal memory (V2): beliefs + episodes  → memory_state.db
  ├─ Knowledge Library (optional inject)       → knowledge_* stores
  └─ Optional scale adapters
       • pgvector (auto when Postgres DSN is set) / Qdrant
       • Postgres dual-mirror or state.role=primary
       • Neo4j (dual-write; Dashboard still paints SQLite)

Store	Role	Default
V2 cognitive	“Who I am / what we said”	SQLite primary on one node
Knowledge Library	“What the docs say” + citations	Separate store
Dense vectors	Episode/belief embeddings	sqlite-vec → pgvector when you leave one node
Neo4j	Dual-write of belief triples	Optional
Postgres	Multi-process state mirror / primary	Optional

Operator checklist

Personal memory — defaults; chat “Remember my favorite color is teal.” then “What color?”
Docs — ingest Knowledge Library; keep Inject Knowledge into chat on (Settings → Memory).
Federated search — Dashboard → Search all knowledge → Federated (MEM / KB chips).
Explain recall (optional) — Settings → Memory → Explain recall; chat workbench shows Memory context with channel chips.
Smart Knowledge search (optional) — expand inject to all active libs on technical questions.
Memory admin (/memory) — graph + entities/beliefs (below).
Smoke — pwsh -File scripts/memory_smoke.ps1 · Smoke matrix · Recent features
Optional Neo4j — only if you want graph dual-write (below).
Scale — set KAZMA_DATABASE_URL and CREATE EXTENSION vector. pgvector becomes the dense engine automatically (KAZMA_PGVECTOR=0 keeps sqlite-vec). Do not set KAZMA_MEMORY_STATE_ROLE=primary until python scripts/reconcile_memory_mirror.py --dry-run is clean.

Memory admin page (`/memory`)

Use this page to clean topology without raw SQL.

Goal	How
See the belief graph	Top Graph & health canvas; Refresh if labels look stale. Truncation banner also reports connections hidden by the node cap.
Group / ungroup a node	Inspect → Group under→ (click parent) or Ungroup. View-only — beliefs are untouched.
Find an entity beyond the top 150	Entities search box → type the name/alias (FTS5, diacritic-insensitive); use Load more if “Showing X of Y” shows more
Rename hub “You” → brand name	Entities: find person User / `ent_…` or hub → Rename → e.g. `Mubder`. Canvas hub should show that name.
Rename a project node	Click node or entity row → Rename (id stays `shipx`; label becomes `ShipX`)
Focus list ↔ graph	Click a row to zoom the canvas; click a node to highlight the list
Fix a wrong belief	Beliefs tab → Edit (single modal: object / predicate / subject)
Undo a mistaken edit/invalidate	Click [Undo] on the action toast (60s window) — or restore from Maintenance → backups for older mistakes
Merge duplicate shells	Set Src + Tgt → Merge (beliefs rewired to target; receipt shows the count)
Link two entities	Src + Tgt + predicate → Link
Drop junk beliefs	Select → Invalidate
Why was a belief used?	Click a belief → drawer shows “recalled N× · last … · from `episode`”; Probe from this belief to see neighbors

Hub identity note

The canvas center node is always id=user. A separate person shell (ent_… named User) is treated as the same self: rename updates the hub display name, and list click focuses the hub (graph_id: user). Do not expect a second “You” node for that shell.

Deep dive: Memory & RAG — Memory admin UI.

Settings that matter

UI: Settings → Memory (/settings?tab=memory)
Includes isolation, KB toggles, backends, Neo4j Test/Sync, and embedder (no separate Embedder tab).

Setting	Effect
`merge_knowledge_into_chat`	Inject labeled KB into supervisor next to V2 memory
`promote_kb_to_episodes`	Soft-copy top KB hits into episodic rows (tagged)
`memory.backends.*`	Vector / state / graph adapters + failover
Graph provider `neo4j`	Dual-write triples; topology paint stays SQLite
`tenant_mode`	shared / per_platform / per_user
`KAZMA_MEMORY_ENFORCE_TENANT=1`	Scope `/memory` reads, mutations, undo, and graph-clear by request tenant (off = `default`)

Optional Neo4j

docker compose -f deploy/docker-compose.neo4j.yml up -d

# Env install default (fail-open if server down):
export KAZMA_NEO4J_DEFAULT=1
export KAZMA_NEO4J_PASSWORD=YOUR_PASSWORD_HERE

Or UI: Graph store Neo4j → Save → Test Neo4j → Sync beliefs → Neo4j.

Masked password *** in the form does not wipe the vault secret on Test.
Clear graph invalidates SQLite beliefs and deletes that tenant’s Neo4j edges. A manual Sync is only needed if dual-write was down during the clear.
Do not make Neo4j a required install for single-user setups.

Maintenance

Job	Cadence
macro_sleep (decay / tiers) + ego-anchor backfill + FTS drift rebuild	~6h
backup + export (beliefs, episodes, merges, archive, audit JSONL) + mirror-drift warning	~24h
global reconsolidation (dedupe + re-embed + count recompute)	~24h; auto-partitions large corpora

Dashboard: Run reconsolidation, queue retry / Clear failed, component health board.

What not to do

Do not dump KB chunks into the beliefs table as raw SPO without provenance.
Do not require Neo4j for a normal install.
Do not set KAZMA_MEMORY_STATE_ROLE=primary until python scripts/reconcile_memory_mirror.py --dry-run reports no dead-in-mirror / only-in-mirror rows.
Do not treat “memory V2” as a product version entity (hygiene blocks subjects like kazma_v2_4_0).
Do not rewrite belief subject ids by hand to “fix” labels — use Rename (display) or Merge (identity).
Do not expect empty person shells with zero beliefs to appear as extra graph nodes — self shells focus the hub.

Memory and RAG
Knowledge Library
Plan: docs/plans/MEMORY_REMAINING.md
Audit: AUDIT_MEMORY_SYSTEM_2026-08-24.md (M-01..M-17 closed)
Scale: #76 · #77 · #78