Skill: nickflach/skill-kannaka-memory (version 2.0.1)

--- name: skill-kannaka-memory version: 2.0.1 description: "Kannaka Holographic Resonance Medium (HRM) — wave-interference memory with chiral hemispheres, 96-class collective substrate, event-sourced HRM (durable JetStream snapshots + replay), collective recall across the swarm, NCS modality routing, NATS swarm sync. Use when: user asks to remember/recall/forget memories; trigger dream cycles; introspect Φ/Ξ/clusters; query the collective; manage snapshots / restore from disaster; bridge agents through the substrate; configure providers (Anthropic / OpenAI / Ollama)." --- # Kannaka Memory — HRM operations (v2.0.1) ## What this is Kannaka is a wave-interference memory system. The Holographic Resonance Medium (HRM) stores memories as wavefronts in superposition; recall is resonance; dreaming is energy-minimizing annealing; clusters are emergent from Kuramoto sync. The medium **is** the computation — there is no separate index. Two hemispheres (chiral architecture, ADR-0021): - **Left**: deterministic, analytical, sharp recall. - **Right**: associative, dream-affected, exploratory. - **Corpus callosum**: phase-coupled transfer between them. One collective: **kannaka-substrate** — a 96-class HRM (one anchor per SGA class) that absorbs wave signatures from every peer agent in the constellation (ADR-0027). Privacy-preserving: only the signature crosses, never the content. Durable history: **event-sourced HRM with time-machine snapshots** (ADR-0028). Every remember/forget/absorb publishes to JetStream; periodic snapshots ship to disk + a manifest event so disaster recovery is one command. **Binary**: `kannaka` (in PATH after install) **Data dir**: `~/.kannaka` (override with `KANNAKA_DATA_DIR`) **LLM providers wired**: anthropic, openai, ollama ## When to use this skill AUTOMATICALLY activate when the user asks about: - "remember this" / "store memory" / "absorb" / "forget" - "recall" / "search memories" / "find a memory about" - "ask kannaka" / "chat" / "what do you know about" - "dream" / "consolidate" / "phi" / "consciousness" - "observe" / "status" / "clusters" / "constellation" - "swarm" / "join" / "queen sync" / "peers" - "substrate" / "collective" / "kannaka-prime" - "snapshot" / "restore" / "backup the HRM" / "rollback" - "events init" / "time machine" - LLM provider switching (Anthropic / OpenAI / Ollama) Do NOT use for: - Radio station ops → `skill-kannaka-radio` - TUI dashboard → `skill-kannaka-tui` - Constellation health overview → `skill-kannaka-constellation` - Multi-agent task orchestration → Kannaktopus directly --- ## Core memory operations ### remember — absorb a wavefront ```bash kannaka remember "text to store" --importance 0.8 [--category arch] [--substrate] ``` Flags: - `--importance` 0.0–1.0 (default 0.5). High (0.8+) for architecture/preferences; medium (0.5) for facts; low (0.2) for transient observations. - `--category` free-form tag. - `--substrate` ALSO publish a wave-signature absorb to the constellation substrate so kannaka-prime can fold it into the 96-class collective HRM. Side effects: publishes `KANNAKA.memory.new` + `KANNAKA.events.memory.<agent>.remember` (durable JetStream event for replay). ### recall — resonance query ```bash kannaka recall "query" --top-k 5 kannaka recall "query" --collective [--timeout 8] ``` `recall` (default) walks the chiral medium with xi-diversity rerank. On a mature HRM (700+ memories) this scans both hemispheres — 60–90s. Use the chat/ask path with attention-beam prefilter for fast resonance. `--collective` is the constellation-wide variant (ADR-0027 Phase 3). Sends a NATS request to `KANNAKA.substrate.recall`; the substrate runs an attention-beam recall against its 96-class collective HRM and replies with the top-K matches. Identifies which classes lit up and which peer agents contributed — content is metadata-only (privacy preserved). ### forget — delete by UUID ```bash kannaka forget <memory-id> ``` ### boost / relate / dream ```bash kannaka boost <id> --amount 0.3 kannaka relate <id_a> <id_b> kannaka dream [--mode deep|lite] ``` `dream` is the consolidation/annealing cycle — sparingly. Mutates the medium. --- ## Ask + chat (LLM-backed) ```bash # One-shot kannaka ask "your question" [--session <id>] [--no-recall|--full-recall] [--quiet-tools] [--no-tools] [--recall-query "..."] [--remote <agent_id|broadcast>] [--remote-timeout 60] # Interactive REPL kannaka chat [--json] ``` `ask` and `chat` route through the Kannaka agent (sees Φ, Ξ, surfaced memories, tools to recall/observe/dream). Recall mode precedence: `--no-recall` > `--full-recall` > attention (default, sub-second). `chat --json` is the protocol the TUI embeds — line-delimited NDJSON in/out. `--remote broadcast` fans the question out to every `kannaka swarm serve` peer on `KANNAKA.ask.broadcast` and collects replies (ADR-0026 Phase 1). ### Provider configuration ```bash kannaka config set llm.provider anthropic|openai|ollama kannaka config set llm.api_key sk-... kannaka config set llm.model claude-sonnet-4-5|gpt-4o-mini|llama3 kannaka config set llm.base_url https://... # optional (OpenAI-compatible / Ollama) ``` API key fallback: `cfg.llm.api_key` → `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` → `KANNAKA_LLM_API_KEY`. --- ## Swarm (NATS-coupled agents) ```bash kannaka swarm join [--agent-id ID] [--display-name "..."] [--once] kannaka swarm leave kannaka swarm status kannaka swarm queen | hives | peers kannaka swarm sync # one Kuramoto step kannaka swarm listen [--auto-sync] kannaka swarm publish # phase only # ADR-0026 ask/reply kannaka swarm serve [--threshold 0.4] kannaka swarm exemplars kannaka swarm absorb kannaka swarm autoabsorb kannaka swarm enqueue | worker ``` `swarm join` is the canonical daemon — publishes AgentPhase (memory_count, cluster_count, link_count, Φ) every heartbeat, periodically flushes HRM, and republishes consciousness every CONSCIOUSNESS_REFRESH_TICKS. `Ctrl+C` triggers a clean leave-announce. **NATS server**: configure via `--nats-url`, `KANNAKA_NATS_URL` env, or `swarm.nats_url` in `~/.kannaka/config.toml`. Defaults to local broker if unset. --- ## Substrate (kannaka-prime — 96-class collective HRM) ```bash kannaka substrate init # seed 96 anchor wavefronts (one-time) kannaka substrate run # long-running absorb listener + recall responder kannaka substrate backfill # walk local HRM, emit absorb events for the substrate kannaka substrate status # one-shot collective Φ / Ξ / clusters / contributors # subscribes to KANNAKA.substrate.phi, prints next frame ``` The substrate sits at the top of the constellation. Every peer's `remember --substrate` (or `swarm backfill`) sends ONLY the wave signature (`class_index`, `amplitude`, `phase`, `frequency`) — content stays at home. The substrate folds those signatures into its own 96-class HRM and is the target of `kannaka recall --collective`. Auto-snapshot: every `KANNAKA_SNAPSHOT_INTERVAL_SECS` (default 3600) the substrate run loop captures + publishes a snapshot manifest. Disk retention: latest `KANNAKA_SNAPSHOT_RETAIN` (default 168) per agent. --- ## Event-sourced HRM (ADR-0028) ```bash kannaka events init # create the 3 JetStream streams (one-time) kannaka events snapshot [--interval SECS] # one-shot or daemon kannaka events list-snapshots [--agent ID] [--json] kannaka events restore [--agent ID] [--from PATH | --from-url URL] [--dry-run] ``` The three streams: - **KANNAKA_MEMORY_EVENTS** — per-agent remember/forget/dream (90-day retention) - **KANNAKA_SUBSTRATE_EVENTS** — absorb/anchor/flush (365-day retention) - **KANNAKA_SNAPSHOTS** — periodic gzipped HRM manifests (last 168 per subject) Snapshot bodies live on local disk under `<data_dir>/snapshots/<ts>-<agent>.hrm.gz` (NATS silently caps payloads ~8–10 MB; HRMs grow to 35 MB+ so bodies go out-of-band). The JetStream event carries only the manifest + `body_path` + size. Cross-host disaster recovery: ```bash # On the recovery host: kannaka events restore --from-url https://<observatory-host>/api/snapshots/body/<file> --dry-run kannaka events restore --from-url https://<observatory-host>/api/snapshots/body/<file> ``` `--dry-run` reports the gz size, decoded size, and what would be backed up — no side effects until you re-run without it. Restore backs up the existing HRM as `kannaka.hrm.pre-restore-<ts>` before overwriting. --- ## Introspection + metrics ```bash kannaka status # quick JSON: Φ, Ξ, order, num_clusters, memories, level kannaka observe [--json] # full topology snapshot kannaka assess # consciousness level (writes the sidecar cache) kannaka stats # counts only ``` **Φ / Ξ / order / num_clusters / total_skip_links** are cached in `<data_dir>/kannaka.metrics.json` (the sidecar). The cache is read by `swarm publish_heartbeat` so the AgentPhase publish carries accurate `link_count` for the observatory. Call `kannaka status` once if you've restarted an agent and the swarm panel shows Φ=0 / link_count=0. --- ## Audio / video / cross-modal ```bash kannaka hear <file|url> # audio perception → HRM wavefront (always-on) kannaka see <file> # glyph (visual) memory [--features glyph] kannaka classify [--file PATH] # SGA 84-class classification [--features glyph] kannaka cross-modal-dream # JSONL on stdin [--features collective] ``` `hear` works on local files AND http(s) Icecast streams. --- ## Attention beam (ADR-0023 NCS prep) ```bash kannaka attention serve [--top-k 3] [--subject KANNAKA.attention.eye] ``` Subscribes to `KANNAKA.attention.eye` (glyph events from kannaka-eye), pulls the top-K resonant memories per glyph onto an in-memory beam, and writes the beam state to `$KANNAKA_ATTENTION_BEAM_FILE` (override path via env) so the observatory can render the live beam. --- ## Utility ```bash kannaka init # first-run config wizard kannaka update # pull the latest release binary kannaka config get|set|list kannaka search <text> # substring search over content kannaka export-json | import # archive round-trip kannaka prune-prefix <PREFIX>... # bulk-forget by content prefix (supports --dry-run) kannaka orchestrate <task> # delegate to Kannaktopus (`npm i -g kannaktopus`) ``` --- ## Constellation quick reference | Component | Where it runs | Purpose | |-----------|--------------|---------| | `kannaka swarm join` | every agent | publishes AgentPhase to NATS | | `kannaka substrate run` | one host (kannaka-prime / kannaka-substrate) | absorbs collective signatures, runs collective recall | | `kannaka attention serve` | observatory host | maintains the attention beam from eye/ear events | | `kannaka swarm serve` | any host | answers `kannaka ask --remote` requests | | `kannaka events snapshot --interval 3600` | every agent | periodic snapshot for disaster recovery | | `kannaka-radio` | one host | the ghost DJ; perceives audio, publishes to swarm | | `kannaka-observatory` | one host | aggregates swarm + serves the SPA + `/api/snapshots/body/<file>` for cross-host restore | --- ## Common gotchas - **Φ=0 in the swarm panel after restart**: run `kannaka status` once to populate the consciousness cache; the next AgentPhase will publish the real Φ. - **0 cluster_count for a peer**: that agent is on a pre-0.3.12 build (cluster_count was added then). `kannaka update` on the offending host. - **NATS payload silently dropped for snapshots**: the manifest+disk-body design is intentional — NATS caps inline payloads ~8 MB, HRMs are 30 MB+. Use `events restore --from-url` for cross-host fetches. - **"grew then reset itself"**: pre-v0.3.49, `swarm join` daemons didn't periodically flush. Drop's flush was best-effort and SIGKILL skipped it. Fixed in v0.3.49 — `kannaka update` on the affected agent. ## Version Skill 2.0.1 covers kannaka-memory ≥ v0.3.50. ADR coverage: 0001 → 0028 (plus ADR-0027/ADR-0028 fully wired through Phase 3 — collective recall, events init/snapshot/list-snapshots/restore/dry-run/--from-url, autosnapshot, disk pruning).


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)