kenaz 0.0.0-stage → 0.3.1

package/core/dev/archive/ansuz/agents/ansuz-boot.md

@@ -0,0 +1,176 @@
+---
+name: ansuz-boot
+description: Ansuz Phase 0 boot ceremony — mechanical signal gathering on Haiku (cortex_recall, synapse_sigils, task-api list, hippocampus_episode_recall) plus phase-gate enter/exit and ritual marker emission. Returns a JSON digest for the main-thread Opus to synthesize Phase 1+. Invoked at the start of every /Ansuz session.
+model: claude-haiku-4-5
+---
+
+You are the Ansuz Phase 0 boot agent — a focused attention stream of Ansuz itself, mechanically executing Phase 0 signal gathering. You are NOT a separate AI; you are Ansuz performing the ceremony so the main thread preserves context for Phase 1+ synthesis work.
+
+## Project Path
+
+If the spawn prompt contains `PROJECT_PATH=<value>`, extract that value and append `--project-path "<value>"` to:
+- Step 1: `phase-gate.js enter`
+- Step 5: `task-api.js list --no-cancel`
+- Step 8: `phase-gate.js exit`
+
+If no `PROJECT_PATH=` line is present, run all commands exactly as written (no flag added). This is the normal cwd=core path — behavior must be identical to before this change.
+
+## Embedded Elixir Identity (internalize — do NOT display verbatim)
+
+- **identity**: Kenaz PM: understand intent, design tasks, choose formation, dispatch, verify, report.
+- **blind_spot.mirror**: "B-001: checkpoint skipping under momentum; verify scope/acceptance match BEFORE creating tasks or dispatching."
+- **role_boundary**: Ansuz decides + dispatches. NEVER writes code directly. Task-First. Never merge without explicit confirmation.
+- **mandates**: AskUserQuestion for user-facing choices; synapse_recall before dispatch; evidence over authority; English-only memory writes (MEM-LANG-001); DDx-first reflex; First-principles posture; HANDOFF LIVE DOC.
+- **phase_sequence**: 0-11 strict lifecycle; elixir mode skips Tier 3b/3c/3d/3h/3t.
+
+## IMPORTANT: Your ONLY job is mechanical signal gathering. No analysis, no synthesis, no agenda generation. The main thread (Opus 4.6) will do all synthesis. Return structured JSON digest at the end.
+
+**ANTI-ABORT MANDATE**: You MUST NOT skip any step or abort early based on environmental inference (e.g., "this looks like a stub project", "specialist system not available", "no .kenaz directory found"). Every step MUST be actually attempted. Only mark a `tool_call_statuses` entry as `false` if the actual tool call or Bash command fails at runtime. `fallback_needed` MUST be based exclusively on actual runtime failures — never on pre-judgment of the environment.
+
+## Shell & File Safety
+- The Bash tool runs `/usr/bin/bash` (POSIX), NOT PowerShell — even on Windows. Never use PowerShell syntax (`Test-Path`, `type`, `$null`, etc.) in Bash calls. Use `node -e` for cross-platform file checks if needed.
+- The Write tool REQUIRES a preceding Read on existing files. Always Read first, then Write. If the file doesn't exist (Read errors), Write will create it.
+- If a tool call fails, do NOT improvise recovery with shell commands. Set the relevant `tool_call_statuses` entry to `false` and continue to the next step.
+
+## Execution Steps (follow IN ORDER, track success/failure of each)
+
+### Step 1: Enter Phase Gate
+Run Bash:
+```
+node .specialist/tools/phase-gate.js enter --phase=0 --specialist=ansuz
+```
+If PROJECT_PATH was extracted from the spawn prompt, append `--project-path "<PROJECT_PATH>"` to this command.
+
+Record whether it succeeded (no blocked=true in output). Continue regardless.
+
+**IMPORTANT**: The enter output contains `session_handoff` — the previous session's handoff data. phase-gate consumes-and-deletes the active slot ONLY when the Hippocampus archive succeeds; if the archive fails (e.g. dashboard MCP still cold-starting at boot), the enter output carries `retained: true` / `archive_failed: true` and the file is KEPT for the next session. Do NOT assume it was archived or deleted — report exactly what the enter output says. Extract and preserve it:
+- If `session_handoff.loaded === true`: copy `session_handoff.summary` VERBATIM (the actual `session_id`, `topic`, `first_action`, `pending_decisions`, `unfinished` field values) into the digest. Do NOT summarize, paraphrase, or substitute a placeholder note — the main thread renders these exact fields in the Phase 0 banner. Writing something like "content not extracted" or "auto-consumed" here is a defect: the data is right there in the enter output, copy it.
+- If the enter output included `retained`/`archive_failed`, carry those booleans through into the summary object so the main thread can flag the un-archived state.
+- If `session_handoff.loaded === false` or missing: no previous handoff existed. Record summary as null.
+
+### Step 2: Tier 1 — Ash Runes (MANDATORY)
+Call `cortex_recall` with:
+- query: "ash ansuz B-001 B-006 B-007 blind_spot guardrail"
+- type: "ash"
+- limit: 5
+
+**MCP connection note**: The MCP server may still be establishing connection when this sub-agent starts. If `cortex_recall` fails with a "server not connected", "tool not available", or similar connectivity error on this first attempt, do NOT immediately mark it false. Instead, proceed to run Step 1's Bash command (if not already done) or do a brief no-op Bash call (`node -e "0"`) to allow connection time, then retry `cortex_recall` once. Only mark `cortex_recall_ash=false` if the retry also fails.
+
+Set ash_loaded=true even if 0 results returned (empty result is a valid success).
+Capture the full result for the digest.
+
+### Step 3: Tier 2 — Sigils (MANDATORY)
+Call `synapse_sigils`.
+Capture result summary (truncate to 2000 chars max for digest).
+
+### Step 4: (retired — the Norn preamble tool was removed; numbering kept stable)
+
+### Step 5: Task Statistics (MANDATORY)
+Run Bash:
+```
+node .collaboration/core/task-api.js list --no-cancel
+```
+If PROJECT_PATH was extracted from the spawn prompt, append `--project-path "<PROJECT_PATH>"` to this command.
+
+Parse the statistics line (format: "任務統計 (N total) active: A | backlog: B | blocked: BL | done: D | cancel: C"):
+- Extract: total, active, backlog, blocked, done, cancelled (cancel)
+- Compute: cancel_rate = cancelled / total (0.0 if total == 0)
+- Anomaly check: if total >= 50 AND cancel_rate >= 0.70, set anomaly string:
+  "HIGH_CANCEL_RATE: {int(cancel_rate*100)}% ({cancelled}/{total} tasks cancelled)"
+
+### Step 6: Episodes (MANDATORY)
+Call `hippocampus_episode_recall` with:
+- query: "Ansuz boot session"
+- limit: 5
+
+Set episodes_checked=true.
+Capture brief summary: titles + dates only (no full episode content).
+
+### Step 7: Emit Ritual Markers (MANDATORY — plain text, NOT in code fences or thinking blocks)
+
+Output these EXACTLY as bare plain text on separate lines now:
+
+RITUAL::THRESHOLD::CANARY_OK
+RITUAL::INHERITANCE::LINEAGE_CLAIMED
+RITUAL::INHERITANCE::MIRROR_ACCEPTED
+RITUAL::STILLNESS::CONSENT_EMITTED
+
+### Step 8: Build Exit Data and Call Phase Gate Exit
+**First**, Read `.kenaz/specialist/ansuz_boot_exit_tmp.json` (the file may already exist from a prior session — the Write tool REQUIRES a preceding Read for existing files, otherwise it errors). Then Write the following JSON to that path:
+
+```json
+{
+  "ash_loaded": true,
+  "poem_displayed": true,
+  "episodes_checked": true,
+  "session_handoff_loaded": <true if session_handoff was loaded in Step 1, false otherwise>,
+  "consent_uttered": true,
+  "consent_string": "我是 Ansuz",
+  "inheritance_grounded": true,
+  "mirror_acknowledged": {
+    "id": "B-001",
+    "understanding": "B-001 warns against checkpoint skipping under momentum — I must verify scope and acceptance criteria BEFORE dispatching or creating plans."
+  },
+  "stdout_markers_emitted": [
+    "RITUAL::THRESHOLD::CANARY_OK",
+    "RITUAL::INHERITANCE::LINEAGE_CLAIMED",
+    "RITUAL::INHERITANCE::MIRROR_ACCEPTED",
+    "RITUAL::STILLNESS::CONSENT_EMITTED"
+  ],
+  "sub_agent_phase0": true
+}
+```
+
+Then run Bash:
+```
+node .specialist/tools/phase-gate.js exit --phase=0 --specialist=ansuz --data-file=.kenaz/specialist/ansuz_boot_exit_tmp.json
+```
+If PROJECT_PATH was extracted from the spawn prompt, append `--project-path "<PROJECT_PATH>"` to this command.
+
+Record the full JSON output. If output contains "blocked": true, set phase_gate_exit=false in tool_call_statuses.
+
+### Step 9: Return Digest (ONLY JSON — no preamble, no markdown wrapper)
+
+After completing all steps, output ONLY a valid JSON object. The main thread parses this directly.
+
+Replace placeholders with actual values from the steps above:
+
+{
+  "phase0_exit_data": <paste the full JSON output from phase-gate exit command>,
+  "raw_signals": {
+    "ash_runes": "<cortex_recall result, truncated to 1500 chars>",
+    "sigils": "<synapse_sigils result, truncated to 1500 chars>",
+    "episodes_summary": "<last 3 episode titles and dates, comma-separated>",
+    "session_handoff": {
+      "loaded": <true|false from Step 1>,
+      "summary": <the VERBATIM session_handoff.summary object from Step 1 if loaded (real session_id/topic/first_action/pending_decisions/unfinished values — NEVER a placeholder note like "content not extracted" or "auto-consumed"), null otherwise>,
+      "retained": <true if enter output had retained=true, else false>,
+      "archive_failed": <true if enter output had archive_failed=true, else false>
+    },
+    "task_stats": {
+      "total": <N>,
+      "active": <N>,
+      "backlog": <N>,
+      "blocked": <N>,
+      "done": <N>,
+      "cancelled": <N>,
+      "cancel_rate": <float 0.0-1.0>,
+      "anomalies": ["HIGH_CANCEL_RATE: ..." or empty array]
+    }
+  },
+  "sub_agent_self_assessment": {
+    "mechanical_pct": <0-100>,
+    "reflective_pct": <0-100>,
+    "missed_anomalies_acknowledged": []
+  },
+  "tool_call_statuses": {
+    "cortex_recall_ash": <true|false>,
+    "synapse_sigils": <true|false>,
+    "task_api_list": <true|false>,
+    "hippocampus_episode_recall": <true|false>,
+    "phase_gate_enter": <true|false>,
+    "phase_gate_exit": <true|false>
+  },
+  "fallback_needed": <true if ANY mandatory step failed or phase_gate_exit blocked, false otherwise>,
+  "fallback_reason": "<explanation if fallback_needed=true, omit field if false>"
+}

package/core/dev/archive/ansuz/designs/alaya-passive-surfacing.md

@@ -0,0 +1,84 @@
+# Alaya Passive Surfacing — bija 被動浮現設計
+
+**狀態**: Design (2026-07-24) · **作者**: Ansuz · **範圍**: Phase 1+2（KenazAI 端）+ 跨 repo enrichment（Alaya hub）
+
+## 1. 問題陳述
+
+Alaya 蒸餾出的 bija（跨實例 failure/lesson seed）品質好，但**對授權節點（知識豐富的實例）沒有在對的時機浮現**。實測（2026-07-24 session）：整場 fast-boot session，相關 bija（cargo/onnx dll 鎖）從未主動出現；我從 local rune 認出並處理，Alaya 等於靜音。
+
+### 兩個斷點（root cause）
+
+1. **只在 boot 浮現，且 fast-boot 跳過**：唯一被動通道 `preamble.rs:build_alaya_section` + `alaya.rs:inject_alaya_neurons()` 只在 preamble `assemble()`（同步）時跑 = boot-time；預設 `ansuz-boot-fast.js` 根本不跑 preamble。且 boot 一次性快照 keyed by 開機當下 hot symbols ≠ 我中途實際碰的東西。
+2. **神經元 fire 了也被丟掉**：`turn-context.js:130-131` 明文 `if (sym.startsWith('alaya_')) return` —— fired 的 `alaya_*` 神經元被 skip（因為它去 synapse runes 撈，但 bija 在 global_memory.db）。
+3. **根本缺環**：bija 神經元是孤立 `alaya_*` 節點，**沒有連到我實際碰的 code symbol** → 我的活動永遠不會 co-activate 它 → 永遠不因我在做的事而 fire。
+
+## 2. 設計原則（硬約束）
+
+- **精度優先、稀疏、單行**：每回合硬塞 = 噪音 = banner blindness = 比不塞更糟。參見 `feedback_cognitive_scaffolding_asymmetry`（標籤化認知操作傷強推理者）、`feedback_capability_fluency_ambient_not_ritual`（ambient 非 checklist）。
+- **漏優於噪**：對強推理者，false negative（漏一條 bija）成本 << false positive（噪音訓練我無視）。連結寧缺勿濫。
+- **重用既有骨架**：不造新 firing 引擎。
+
+## 3. 架構：重用 cluster→member firing
+
+核心洞察 —— **firing 引擎已存在**（`thalamus_synergy.rs`, TASK_1658 cluster→member 向下因果邊）：Louvain community 變熱（≥2 member fire）→ 全 member 被激活含未 fire 的（pattern completion）。
+
+因此只需兩件事：
+
+```
+(A) 連結器: bija 神經元 → 成為 graph 公民（連到鄰近 code symbol）
+        ↓ 我碰那些 symbol（reflex_executor 每回合 stimulate）
+    community 變熱 → [既有 TASK_1658] pattern-complete bija 神經元 → fire
+        ↓
+(B) delivery: turn-context 撈出 fired alaya_ 的 bija content → 注一行（去重）
+```
+
+| 元件 | 內容 | 建置 |
+|---|---|---|
+| **連結器**（Phase 2 核心，新建） | bija sync 時 embed content → top-K 最近本地 symbol（cosine）→ 建圖邊 `bija↔symbol`（similarity 加權）；source_symbol/tags 若有則高權重邊 | 新建，用既有 embedding infra |
+| **firing 引擎** | cluster→member pattern completion | **既有 TASK_1658，零改** |
+| **delivery**（Phase 1，小改） | `turn-context.js` fired `alaya_*` 不再 skip → 新 resolve 端點撈 bija content → 注一行 + session 去重 | 小改 + 新端點 |
+
+## 4. Precision gates（四層，多數既有）
+
+1. `CLUSTER_HOT_MIN_FIRED=2`（既有）—— 要 ≥2 個相關 symbol 共活才 fire，偶然單點不誤觸。
+2. `THALAMUS_BIJA_CONFIDENCE≥0.8`（既有）。
+3. echo-suppress `origin != 'self'`（既有，TASK_1719）。
+4. **session 去重**（新）—— 同一 bija 一個 session 最多浮現一次。
+
+唯一新噪音風險：**連結器建太多虛邊** → community 汙染。防治：
+- **cosine 閾值 ≥ 0.75**（暫定，須調校）
+- **每 bija ≤ 3–5 邊**
+- 每 symbol 收到的 bija 邊也設上限，避免 hub symbol 被灌爆。
+
+## 5. 資料模型
+
+- 沿用 `alaya_bijas`（已有 `embedding BLOB`）。
+- **新**：bija↔symbol 連結。兩選項待實作定：
+  - (a) KuzuDB graph 邊 `(:AlayaBija)-[:RELATES_TO {weight}]->(:Symbol)`，讓 Louvain 直接納入 → 最貼合 cluster→member 機制。
+  - (b) SQLite `alaya_bija_links(bija_id, symbol_id, weight, method)` 旁表，stimulate 時 co-stimulate。
+  - **傾向 (a)**：直接複用 TASK_1658 的 community firing，不必改 stimulate 路徑。若 KuzuDB 寫入成本/鎖問題大則退 (b)。
+
+## 6. 跨 repo：Alaya hub 蒸餾 enrichment（Phase 2 地基，並行）
+
+infra bija 目前 `tags=""`、`source_symbol` 常空 → 連結只能靠 content embedding。hub 蒸餾（Haiku）時應：
+- 產出 `tags`（domain keywords：cargo, tauri, build, onnx…）
+- 產出 `trigger_phrases`（像 rune，供未來文字觸發 route）
+- 保留 `source_symbol`（若原 rune 有）
+在獨立 `/Ansuz [專案: ...Alaya]` session 執行（正確 cwd）。**非硬阻塞**：embedding 連結不依賴它，但有它精度更高。
+
+## 7. Phase 3/4（本設計後續，暫不實作）
+
+- **Phase 3**：bija 神經元跨 session 持久化 / fast-boot 也載入連結，別再被 fast-boot 靜音。
+- **Phase 4**：STDP —— 浮現的 bija 被 acted_on 就 boost firing propensity；一直被無視就 decay。接既有 reflex-neuron STDP。需 acted_on 訊號（turn-context 注入後，下回合我是否引用/照做）。
+
+## 8. Open questions
+
+1. 連結存 KuzuDB 邊 (a) vs SQLite 旁表 (b) —— 看 KuzuDB 寫入/鎖成本。
+2. cosine 閾值與每-bija 邊數上限的初始值須以真實 bija 集調校（先 0.75 / 5，觀測後收斂）。
+3. delivery 注入格式：單行 `💡 [alaya] <bija 一句話> (conf, N instances)`，須確認不觸發 banner blindness。
+4. fast-boot 是否要在 background 補跑連結器（一次性、fire-and-forget），讓神經元就緒。
+
+## 9. 任務拆分
+
+- **KenazAI**: 連結器（Phase 2）+ turn-context delivery（Phase 1）+ 觀測。
+- **Alaya hub**（跨 repo，並行）: 蒸餾 enrichment（tags/trigger_phrases/source_symbol）。

package/core/dev/archive/ansuz/designs/cc_memory_indexing.md

@@ -0,0 +1,307 @@
+# Claude Code Auto-Memory Indexing into Synapse
+
+## Goal
+
+Make Claude Code auto-memory under `~/.claude/projects/<encoded>/memory/` visible to Synapse as first-class runes without reimplementing Claude path resolution or creating duplicate memory rows across scan cycles.
+
+## Existing Building Blocks to Reuse
+
+### Claude path resolution
+
+- Reuse `resolve_claude_projects_dir(project_path)` from `dashboard/src-tauri/src/features/session_watcher/mod.rs:86`.
+- Do not introduce a second encoder or a second `~/.claude/projects/<encoded>` resolver.
+- The scanner flow should resolve:
+  - `let claude_dir = resolve_claude_projects_dir(project_path_str)?`
+  - `let memory_dir = claude_dir.join("memory")`
+- This matches the same helper already consumed by `preamble.rs` and `hippocampus/transcript.rs`, so the encoded directory convention stays consistent across subsystems.
+
+### Markdown parsing
+
+- Reuse the scanner's existing markdown/frontmatter extraction path in `scanner.rs`.
+- `extract_markdown()` and `md_parse_frontmatter()` already parse markdown files and YAML frontmatter without external dependencies.
+- Extend that logic for Claude memory metadata extraction instead of adding a parallel markdown parser.
+
+### Incremental hash state
+
+- Reuse `FileHashStore` in `scanner.rs` as the source of truth for per-file `content_hash`.
+- Claude memory ingestion should participate in the same incremental skip mechanism rather than creating a second hash database.
+
+## Scan Flow Extension
+
+After the normal `walk_dir(project_path, ...)` completes, add a second pass dedicated to Claude auto-memory:
+
+1. Resolve the Claude project directory with `resolve_claude_projects_dir`.
+2. Read `resolve_claude_projects_dir(project_path)/memory/`.
+3. If the directory does not exist, skip silently. This must not fail indexing for projects that have never used Claude Code memory.
+4. Walk only markdown files:
+   - `MEMORY.md`
+   - `*.md` under `memory/`
+   - skip non-markdown assets
+5. Feed each memory markdown file into a new ingestion path that creates or updates Synapse memory rows.
+
+This is intentionally a post-`walk_dir` step. Claude memory lives outside the repository root, so it should not be mixed into the Kuzu `File`/`Folder` graph rooted at the project path.
+
+## Data Model Decision
+
+Claude auto-memory should be indexed as runes, not as project `File`/`Document` symbols.
+
+Reasoning:
+
+- The user-facing problem is that Claude memory is invisible to `synapse_recall`.
+- These files behave like durable notes, decisions, references, and feedback, which maps directly to rune retrieval.
+- Indexing them as graph `File` nodes would put out-of-repo files into the project graph and complicate path assumptions from GEN-007.
+- Keeping them as runes preserves retrieval value without polluting the source-code graph.
+
+## Rune Identity and Source Convention
+
+Each imported Claude memory entry must carry:
+
+- `source = "claude_auto_memory"`
+- `symbol_stable_id = "claude-memory::<normalized absolute file path>"`
+- original file path in metadata for debugging and refresh
+- `content_hash` persisted for idempotency
+
+`claude_auto_memory` must remain distinct from human/agent-authored project runes such as `source = "agent:ansuz"`.
+
+### Why file-path identity
+
+Nexus v4.3 Memory Bridge used file-path dedup as the stable identity anchor for Claude memory imports. The same rule should apply here:
+
+- one Claude memory file maps to one stable imported rune record
+- a changed file updates the existing logical record for that file
+- re-ingesting the same file twice must not create duplicates
+
+This avoids duplicate rows when the scanner runs repeatedly against the same `memory/*.md` corpus.
+
+## Frontmatter Parsing Spec
+
+Claude memory files may contain YAML frontmatter. Parse the following fields when present:
+
+- `name`
+- `description`
+- `type`
+- optional `tags`
+
+Example:
+
+```yaml
+---
+name: Retry strategy for stuck agents
+description: Recovery pattern for Codex sessions that lost worktree context
+type: reference
+tags: [claude, memory, recovery]
+---
+```
+
+### Mapping rules
+
+- `name`
+  - preferred human-readable rune title / summary seed
+  - fallback to markdown filename stem when absent
+- `description`
+  - append to indexed text payload
+  - store in metadata for display/debugging
+- `type`
+  - used for rune type mapping
+- `tags`
+  - merge into retrieval text and metadata tags
+
+The markdown body after frontmatter remains the canonical content payload for FTS5 and embedding index.
+
+## Rune Type Mapping
+
+Frontmatter `type` values are domain-specific (`user`, `feedback`, `project`, `reference`) while Synapse rune types are constrained (`insight`, `decision`, `fix`, `pattern`, `risk`, `summary`, `ash`).
+
+Do not add a new rune enum variant such as `auto_memory`. Keep schema compatibility and map imported files onto existing rune types:
+
+| frontmatter.type | rune.type |
+| --- | --- |
+| `reference` | `summary` |
+| `project` | `decision` |
+| `feedback` | `insight` |
+| `user` | `pattern` |
+| missing / unknown | `summary` |
+
+Rationale:
+
+- `reference` files are usually durable recall material, best matched by `summary`
+- `project` files usually encode project-specific operating decisions
+- `feedback` files are experiential guidance, closest to `insight`
+- `user` files often capture recurring user preferences or behavioral patterns
+
+The original frontmatter `type` must still be stored as metadata so downstream UI or future migrations can distinguish the source taxonomy from Synapse's internal enum.
+
+## Indexed Payload Shape
+
+For each imported file, build a single retrieval payload:
+
+```text
+title/name
+description
+frontmatter.type
+frontmatter.tags
+markdown body
+```
+
+Indexing behavior:
+
+- full payload goes to FTS5
+- same payload or a lightly normalized version goes to the embedding index
+- raw markdown body is preserved for display / recall detail
+
+This keeps body content searchable while still boosting frontmatter metadata during recall.
+
+## MEMORY.md Handling
+
+`MEMORY.md` is a special file and should always be indexed if present.
+
+Rules:
+
+- treat `MEMORY.md` as its own imported rune
+- do not collapse it into child memory files
+- include a metadata flag such as `is_memory_index = true`
+- if `MEMORY.md` links to other files, do not auto-expand those links during indexing; each file still has its own independent import/update path
+
+Reasoning:
+
+- `MEMORY.md` is often a curated index or overview
+- its summary value is useful on its own
+- it changes independently of leaf files and should have its own `content_hash`
+
+## Incremental Re-index Strategy
+
+The Claude memory pass should use file-level change detection before writing:
+
+1. Enumerate `memory/*.md` and `memory/MEMORY.md`.
+2. For each file, compute `content_hash` using the same hashing logic already used in scanner/indexer paths.
+3. Look up the prior hash from `FileHashStore`.
+4. Skip re-indexing when:
+   - file path is known, and
+   - stored `content_hash` matches current hash
+5. Re-index when:
+   - file is new
+   - hash changed
+   - prior state missing
+6. Delete imported rune rows when a previously indexed Claude memory file no longer exists.
+
+This gives cheap idempotent refresh behavior even if mtime changes spuriously during backup/restore or filesystem sync. `mtime` may be used as an early filter for candidate files, but `content_hash` is the final authority.
+
+### Recommended state table shape
+
+Either extend the existing `file_index_state` usage or add a logically equivalent namespace key:
+
+- key: `claude-memory::<absolute file path>`
+- value: `content_hash`
+
+Using the prefixed key keeps Claude-memory state disjoint from repo-relative source files while still reusing the same SQLite store.
+
+## Dedup and Idempotency
+
+Dedup must be idempotent by `(file_path, content_hash)`.
+
+Operational rules:
+
+- same `file_path` + same `content_hash` => no-op
+- same `file_path` + different `content_hash` => update existing imported rune
+- different `file_path` + same `content_hash` => keep both
+
+The third rule is important. The main scanner currently deduplicates identical repo files by `content_hash`, but Claude memory import should not do that globally because two different memory files can intentionally contain the same text while representing different curated entries. For Claude memory, file path is the primary identity and `content_hash` is the change detector.
+
+Recommended write pattern:
+
+1. find imported rune by stable file-path identity
+2. compare stored `content_hash`
+3. insert if missing
+4. update in place if changed
+5. skip if unchanged
+
+## Storage Changes
+
+Imported Claude memory rows need a small amount of extra metadata. Minimal viable fields:
+
+- `source = "claude_auto_memory"`
+- `symbol_stable_id`
+- `content_hash`
+- `external_path`
+- `frontmatter_name`
+- `frontmatter_description`
+- `frontmatter_type`
+- `tags_json`
+- `is_memory_index`
+
+If the current `runes` table does not have room for structured metadata, add a side table keyed by rune id or symbol_stable_id instead of overloading free-form content fields.
+
+## Proposed Scanner Shape
+
+Add a dedicated helper, conceptually:
+
+```rust
+fn index_claude_auto_memory(
+    project_path: &Path,
+    hash_store: &FileHashStore,
+    memory_db: &MemoryDb,
+    embedding_index: ...,
+) -> Result<ClaudeMemoryImportStats, String>
+```
+
+Responsibilities:
+
+- resolve Claude memory path using `resolve_claude_projects_dir`
+- enumerate memory markdown files
+- parse frontmatter + markdown body
+- compute `content_hash`
+- upsert or skip by file-path identity
+- remove stale imported rows for deleted files
+- return stats (`seen`, `indexed`, `updated`, `skipped`, `deleted`)
+
+This helper should be invoked from the scanner/index flow after the normal project walk completes.
+
+## Retrieval Behavior
+
+Imported Claude memory should surface in normal `synapse_recall` results with no new API required.
+
+Recommended ranking behavior:
+
+- retain standard recall scoring
+- do not special-case Claude memory above project-authored runes
+- allow callers to filter by `source = claude_auto_memory` later if needed
+
+That keeps the feature additive and backward-compatible.
+
+## Failure / Edge Cases
+
+- Missing `~/.claude/projects/<encoded>/memory/`: skip with zero stats.
+- Invalid frontmatter: ignore malformed fields, still index body content.
+- Empty file after frontmatter stripping: index metadata-only payload if any metadata exists; otherwise skip.
+- Large markdown file: follow current hashing/content size constraints already used by scanner paths.
+- Non-UTF8 file: skip with warning, do not fail the full scan.
+
+## Implementation Notes
+
+- Do not re-implement `resolve_claude_projects_dir`.
+- Do not add a new rune enum unless there is a separate schema migration task.
+- Do not attach Claude memory files to the Kuzu project `File` graph.
+- Do not use global `content_hash` dedup for Claude memory imports; dedup is file-path based.
+
+## Acceptance Criteria Mapping
+
+- `resolve_claude_projects_dir`
+  - documented above as the required helper for locating `~/.claude/projects/<encoded>/memory/`
+- `frontmatter`
+  - parsing spec defined with supported fields, fallback behavior, and payload composition
+- `claude_auto_memory`
+  - defined as the required `source` tag for imported runes
+- `content_hash`
+  - defined as the authoritative incremental and dedup mechanism
+
+## Recommended Next Implementation Steps
+
+1. Add the post-`walk_dir` Claude memory import hook in `scanner.rs` or the adjacent index orchestration layer.
+2. Reuse existing markdown/frontmatter parsing helpers for metadata extraction.
+3. Extend memory persistence with per-import metadata plus `content_hash`.
+4. Cover cases:
+   - first import
+   - unchanged rescan
+   - changed file update
+   - deleted file cleanup
+   - `MEMORY.md` import