scratch-incremental-82629d86.json

{
  "totalRawLines": 1301,
  "windowSize": 150,
  "totalWindows": 9,
  "skippedWindows": 0,
  "vccFailWindows": 0,
  "windowLog": [
    {
      "idx": 1,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 49868,
      "untunedCount": 2,
      "v2Count": 1
    },
    {
      "idx": 2,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 26013,
      "untunedCount": 8,
      "v2Count": 9
    },
    {
      "idx": 3,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 15341,
      "untunedCount": 3,
      "v2Count": 2
    },
    {
      "idx": 4,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 19223,
      "untunedCount": 3,
      "v2Count": 3
    },
    {
      "idx": 5,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 25897,
      "untunedCount": 5,
      "v2Count": 4
    },
    {
      "idx": 6,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 30672,
      "untunedCount": 5,
      "v2Count": 7
    },
    {
      "idx": 7,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 11002,
      "untunedCount": 3,
      "v2Count": 4
    },
    {
      "idx": 8,
      "lines": 150,
      "signal": true,
      "vccOk": true,
      "vccChars": 14857,
      "untunedCount": 5,
      "v2Count": 7
    },
    {
      "idx": 9,
      "lines": 101,
      "signal": true,
      "vccOk": true,
      "vccChars": 12730,
      "untunedCount": 0,
      "v2Count": 1
    }
  ],
  "untuned_candidates": [
    {
      "title": "DBSCAN eps parameter too small in embed_atoms.py",
      "body": "Current eps value produces only 5 clusters from 854 atoms (844 singletons/noise) vs. prior 25+ clusters. Atoms linked by 20+ references fail to cluster. Tuning eps upward needed; current value treats similar atoms as noise instead of forming meaningful groups.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "dbscan",
        "eps-parameter",
        "clustering",
        "embedding"
      ],
      "promotion_target": "note",
      "_window": 1
    },
    {
      "title": "Incremental atom clustering re-computes all cluster IDs",
      "body": "cluster-atoms re-runs full DBSCAN, resetting cluster_ids for all 854 atoms and overwriting prior assignments. Breaks concurrent harvest workflows—adding ~30 new atoms nulls ~850 old cluster pointers. Needs incremental DBSCAN variant or post-harvest reconciliation pass.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.8,
      "tags": [
        "clustering",
        "dbscan",
        "incremental",
        "atoms",
        "architecture"
      ],
      "promotion_target": "adr",
      "_window": 1
    },
    {
      "title": "DBSCAN eps threshold on normalized vectors",
      "body": "On L2-normalized embeddings, Euclidean eps relates to cosine similarity via: cos_sim = 1 - eps²/2. eps=0.36 yields cos_sim=0.935 floor, catching only near-paraphrases. Explains why original tuning failed to produce thematic clusters: DBSCAN threshold was mathematically too tight for semantic grouping.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "dbscan",
        "epsilon",
        "cosine-similarity",
        "embedding-threshold"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Concurrent ID generation race condition",
      "body": "add_atom.py, add_cluster.py, add_source.py, migrate_atoms.py all use unguarded SELECT MAX(id)+1. Under concurrent sessions (normal case when multiple /harvest-knowledge runs overlap), two processes read same MAX(id) before either commits, causing primary-key collision. Blocks the new constraint: multiple simultaneous sessions writing atoms.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "race-condition",
        "concurrent-writes",
        "id-generation",
        "critical-bug"
      ],
      "promotion_target": "note",
      "_window": 2
    },
    {
      "title": "Incremental clustering loop architecture",
      "body": "Proper flow: (1) cache embeddings persistently, (2) match new atoms to existing centroids, (3) run DBSCAN only on orphans, (4) re-sweep all atoms against new + existing centroids. Unifies blind embed_atoms.py DBSCAN with reconcile_vault.py centroid-matching. Creates new clusters only when orphans can't fit existing centroids.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.95,
      "tags": [
        "clustering",
        "incremental",
        "architecture",
        "atoms",
        "embeddings"
      ],
      "promotion_target": "adr",
      "_window": 2
    },
    {
      "title": "sqlite-vec for embedding cache with agent ANN access",
      "body": "Chose sqlite-vec vec0 virtual table over plain BLOB column to enable agent-facing ANN/cosine search, not just internal caching. Eliminates per-run Ollama cost (only new/edited atoms re-embed). Future agents can query atoms semantically via native vec0 queries.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.95,
      "tags": [
        "embedding-cache",
        "sqlite-vec",
        "ann-search",
        "agent-tools"
      ],
      "promotion_target": "adr",
      "_window": 2
    },
    {
      "title": "Curated related-links and embedding signals are independent",
      "body": "The `related:` field is LLM-curated at atom-creation time; raw embedding cosine distance is a separate semantic signal. No inherent correlation — explains why atoms with 20 curated related-links didn't land in same DBSCAN cluster as those links. Two different signals, no reason to expect agreement.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.85,
      "tags": [
        "semantic-networks",
        "embeddings",
        "clustering",
        "curation"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Backlog has ~3 duplicate clusters per concept",
      "body": "103 existing clusters accumulated from ~10 separate /harvest-knowledge runs (2026-06-30 to 2026-07-06), each run invoking Phase 4C LLM grouping independently. Results: 3x '8-Phase Memory Write ___', 3x 'Async ... Fan-Out', 3x 'Token Budget ___', 3x 'Parallel Agent .../Git Worktree'. Root cause: add_cluster.py upserts by exact name-string match only; no semantic dedup across runs.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "deduplication",
        "backlog",
        "clusters",
        "fragmentation"
      ],
      "promotion_target": "note",
      "_window": 2
    },
    {
      "title": "Auto-apply atoms above confidence threshold",
      "body": "Design: new atoms matching existing clusters above confidence threshold auto-apply (fast path); below threshold or no match require review before assignment. Balances automation speed with audit trail for edge cases.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.95,
      "tags": [
        "clustering",
        "threshold",
        "auto-apply",
        "review"
      ],
      "promotion_target": "ddr",
      "_window": 2
    },
    {
      "title": "Backlog atoms lack proper YAML frontmatter",
      "body": "~90 of 101 atoms in vault missing proper frontmatter structure (only ~11 have valid YAML head). Example: '8-Phase Agentic Memory Write.md' lacks id, date, related, links. Constraint: migration strategy must upgrade old atoms to modern format, merge if similar, or remove if duplicate/low-quality.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "atom-format",
        "frontmatter",
        "migration",
        "legacy-data"
      ],
      "promotion_target": "note",
      "_window": 2
    },
    {
      "title": "Flow-state.env lacks session isolation",
      "body": ".flow/flow-state.env is a single shared file across concurrent Claude Code sessions; multiple concurrent flows in the same project clobber each other's telemetry attribution. Doesn't block functional pipeline execution (only affects telemetry logging), but prevents accurate flow tracking in multi-session scenarios.",
      "memory_type": "tool_quirk",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "flow-state",
        "concurrency",
        "telemetry"
      ],
      "promotion_target": "none",
      "_window": 3
    },
    {
      "title": "Subagents cannot call AskUserQuestion",
      "body": "Subagents launched in Claude Code flows lack access to AskUserQuestion tool; it does not exist in their context. When needing approval, subagents must report phase completion and suggest next manual steps (e.g., 'Run /plan to proceed') instead of awaiting interactive confirmation.",
      "memory_type": "tool_quirk",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.85,
      "tags": [
        "subagent",
        "flow-architecture",
        "tool-limitation"
      ],
      "promotion_target": "none",
      "_window": 3
    },
    {
      "title": "BEGIN IMMEDIATE for ID lock, embedding outside transaction",
      "body": "Concurrent writes to atoms.db must lock only during ID allocation (BEGIN IMMEDIATE); perform embedding outside the transaction to avoid serializing writers behind Ollama latency. Discovered real concurrent-write collision risk in 4 legacy atoms scripts; pattern prevents stalls.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.85,
      "tags": [
        "concurrency",
        "id-allocation",
        "database"
      ],
      "promotion_target": "none",
      "_window": 3
    },
    {
      "title": "Best-of-N similarity inflates false positives",
      "body": "Selecting best match from large candidate set (800+) causes artificial score inflation even for non-duplicates due to extreme-value statistics. Threshold designed for low-risk additions (0.75) falsely approves high-risk deletions; use separate, stricter threshold for destructive decisions.",
      "memory_type": "insight",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "similarity",
        "scoring",
        "statistics",
        "threshold",
        "matching"
      ],
      "promotion_target": "best_practice",
      "_window": 4
    },
    {
      "title": "High-risk-only testing strategy",
      "body": "Test only operations with genuine branching/complexity: centroid math, threshold bands, concurrent ID ops, cache hit/miss. Skip CLI/glob/writer/glue (boilerplate rarely breaks). Keeps suite focused, reduces noise.",
      "memory_type": "convention",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.8,
      "tags": [
        "testing",
        "posture",
        "convention",
        "design"
      ],
      "promotion_target": "none",
      "_window": 4
    },
    {
      "title": "Concurrent ID allocation via write_txn prevents collision",
      "body": "Use database transaction lock (`id_alloc.write_txn()`) to serialize concurrent add_atom/cluster/source operations. Real threads + contention validated; prevents IntegrityError and duplicate ID assignment.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.85,
      "tags": [
        "concurrency",
        "transactions",
        "id_allocation",
        "locking"
      ],
      "promotion_target": "recipe",
      "_window": 4
    },
    {
      "title": "Similarity thresholds fail for shared-vocabulary domains",
      "body": "When domain vocabulary is highly shared (e.g., all atoms about agents/workflows), similarity scores saturate across the range even for genuinely distinct concepts. Tested: 0.878 threshold produced 29 false positives and 1 false negative; real duplicates (0.83–1.0) and noise (0.80–0.92) ranges overlap completely with no clean separator. No pure-similarity cutoff works at any threshold value for deduplication decisions.",
      "memory_type": "insight",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "deduplication",
        "clustering",
        "similarity-scores",
        "thresholds"
      ],
      "promotion_target": "best_practice",
      "_window": 5
    },
    {
      "title": "Direct membership is zero-error deduplication signal",
      "body": "For clustering deduplication: atoms literally appearing in both clusters (shared_members field) provides the only deterministic signal. Zero false positives, zero false negatives across 663 candidate pairs. Similarity scoring creates noise; direct set membership creates certainty. Use for auto-merge decisions when this evidence is available.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "deduplication",
        "clustering",
        "evidence",
        "signal-detection"
      ],
      "promotion_target": "none",
      "_window": 5
    },
    {
      "title": "Transitive merges via hub nodes over-merge unrelated clusters",
      "body": "Building transitive merge groups: if a hub cluster legitimately touches multiple distinct topics, transitively merging all connected clusters creates false mega-merges. Example: 'Agent Role Archetype' touches 'context loading', 'permission schema', 'role archetypes' — these are distinct, not duplicates. Fix: identify true cliques (every pairwise combination directly evidenced), reject hub-mediated chains. Of 23 merge candidates, 21 were cliques; 2 were invalid transitive chains.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "deduplication",
        "clustering",
        "transitive-closure",
        "graph-merging"
      ],
      "promotion_target": "none",
      "_window": 5
    },
    {
      "title": "Destructive actions require direct user authorization",
      "body": "Agents must refuse destructive operations (content deletion/merging) based on coordinator-relayed claims of user approval. Coordinator messages—even detailed and pre-computed—don't constitute user authorization. Only direct user messages grant escalation for destructive actions. This prevents coordinators from triggering irreversible changes mid-task.",
      "memory_type": "convention",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "agent-protocol",
        "authorization",
        "destructive-operations",
        "safety"
      ],
      "promotion_target": "none",
      "_window": 5
    },
    {
      "title": "Case-sensitive DB names orphan rows on case-insensitive filesystems",
      "body": "On Windows (case-insensitive filesystem): DB rows with case-only-different names (e.g., 'Phase-level Rollback' vs 'Phase-Level Rollback') point to the same physical file. Whichever row is written last wins on disk, leaving earlier DB rows orphaned with no corresponding file. Audit for case-only duplicates when merging.",
      "memory_type": "tool_quirk",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "windows",
        "case-sensitivity",
        "database",
        "filesystem-mismatch",
        "orphan-rows"
      ],
      "promotion_target": "none",
      "_window": 5
    },
    {
      "title": "Header-matching case sensitivity causes silent content loss",
      "body": "Exact-string matching in parse_freeform silently emptied content (26 of 54 atoms, 78–90% loss) when headers used different casing. Detected via git HEAD diff before commit.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 1,
      "tags": [
        "parser",
        "silent-failure",
        "case-sensitivity",
        "legacy-atoms"
      ],
      "promotion_target": "best_practice",
      "_window": 6
    },
    {
      "title": "Concurrency protection gap in atom UPDATE path",
      "body": "new-atom INSERT got write_txn protection; UPDATE path (name-collision merges) has none. Concurrent updates to same atom name can lose data silently—same bug class the fix addresses, missed on this branch.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 1,
      "tags": [
        "concurrency",
        "race-condition",
        "incomplete-fix",
        "add-atom"
      ],
      "promotion_target": "none",
      "_window": 6
    },
    {
      "title": "Lock-scope inconsistency: add_atom vs add_cluster",
      "body": "add_cluster does file writes after write_txn closes; add_atom does them inside. Same PR/architecture doc, diverging lock scopes. Recommend unified pattern (file I/O outside lock).",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 1,
      "tags": [
        "lock-scope",
        "architecture-drift",
        "writer-scripts",
        "concurrency"
      ],
      "promotion_target": "none",
      "_window": 6
    },
    {
      "title": "is_legacy and parse_freeform header-match drift",
      "body": "is_legacy() uses exact strings; parse_freeform() uses case-insensitive aliases. Both handle same headers; can desync silently. Consolidate on _normalize_heading + _HEADING_FIELD_ALIASES.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 1,
      "tags": [
        "legacy-atoms",
        "parser-fragmentation",
        "heading-aliases",
        "sync-risk"
      ],
      "promotion_target": "none",
      "_window": 6
    },
    {
      "title": "Git HEAD diff detects silent content destruction",
      "body": "When parsers silently empty fields (success report but no body), git diff HEAD reveals extent + files before commit. Faster than unit tests catching silent failures.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "debugging",
        "git-forensics",
        "silent-failure-detection",
        "content-loss"
      ],
      "promotion_target": "best_practice",
      "_window": 6
    },
    {
      "title": "Argparse append action defaults to None",
      "body": "argparse with action='append' returns None when no values provided, not []. Must explicitly check for None or set default_factory=list to get empty list instead.",
      "memory_type": "tool_quirk",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "argparse",
        "python",
        "defaults",
        "action-append"
      ],
      "promotion_target": "none",
      "_window": 7
    },
    {
      "title": "Consolidate duplicate transformation logic",
      "body": "In this project, is_legacy() and parse_freeform() each had their own heading-field alias definitions that drifted. Fixed by creating single _HEADING_FIELD_ALIASES dict and _normalize_heading() function consumed by both. Prevents recurring drift.",
      "memory_type": "failure",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "duplication",
        "transformations",
        "single-source-of-truth",
        "maintenance"
      ],
      "promotion_target": "best_practice",
      "_window": 7
    },
    {
      "title": "Thread data through call stack, not hardcoded placeholders",
      "body": "sync_clusters.py had hardcoded {} for atom_related in _match_existing(), masking the parameter. When atom schema changed, matching produced stale results silently. Always thread actual data through intermediate functions instead of hardcoding placeholders.",
      "memory_type": "failure",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "data-flow",
        "staleness",
        "coupling",
        "regression-prevention"
      ],
      "promotion_target": "best_practice",
      "_window": 7
    },
    {
      "title": "add_atom/add_cluster UPDATE lost-update race",
      "body": "UPDATE operations in add_atom.py and add_cluster.py had no transaction protection, silently losing concurrent writes when two writers updated the same atom/cluster simultaneously. Both now wrapped in write_txn. Regression test: test_concurrent_updates_same_atom_no_lost_source.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.95,
      "tags": [
        "concurrency",
        "lost-update",
        "add_atom",
        "add_cluster"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "Lock-scope inconsistency masks concurrency bugs",
      "body": "add_atom.py held write lock across file I/O while add_cluster.py released early, masking missing transaction protection in UPDATE paths. Inconsistent lock scopes across related modify functions hide concurrency bugs. Unified both to release lock before file I/O.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.9,
      "tags": [
        "concurrency",
        "lock-scope",
        "add_atom",
        "add_cluster"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "is_legacy/parse_freeform alias-map divergence",
      "body": "is_legacy and parse_freeform maintained separate alias maps and drifted apart silently, causing content-loss bugs. Now unified to single shared alias map. Lesson: shared state needing cross-caller consistency must have single source of truth.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "is_legacy",
        "parse_freeform",
        "shared-state",
        "alias-map"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "stale_related silent regression in sync_clusters",
      "body": "sync_clusters.py's stale_related always returned empty, silently regressing vs original reconcile_vault.py. Now wires real atom_related data through. Lesson: audit data flow through refactored functions; execution-state marking != actual completion.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "sync_clusters",
        "stale_related",
        "regression",
        "audit"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "Empty-scope harvest triggers full-vault sync",
      "body": "Empty harvest in harvest-knowledge.md Phase 4B silently triggers full-vault sync instead of no-op. Now guarded with explicit empty-scope check. Pattern: harvest-like operations need guards; empty input should be no-op, not trigger full operation.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "harvest-knowledge",
        "empty-scope",
        "edge-case"
      ],
      "promotion_target": "none",
      "_window": 8
    }
  ],
  "v2_candidates": [
    {
      "title": "DBSCAN eps parameter causes 5x under-clustering",
      "body": "embed_atoms.py DBSCAN eps value is too high; 854 atoms merged into 5 clusters instead of expected ~30. Previous vault had 25 clusters. Reduce eps threshold to restore semantic differentiation.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "clustering",
        "dbscan",
        "parameter-tuning",
        "atoms",
        "embedding"
      ],
      "promotion_target": "note",
      "_window": 1
    },
    {
      "title": "DBSCAN eps only catches near-duplicates",
      "body": "eps=0.36 on L2-normalized mxbai vectors yields cosine_sim ≈ 0.935 floor — only catches paraphrases, not thematic groups. Looser eps on short technical atoms collapses vault to one blob. Neither eps-tuning nor DBSCAN alone solve thematic clustering at this scale/diversity.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.9,
      "tags": [
        "dbscan",
        "embeddings",
        "clustering",
        "mxbai"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Related links are independent from embedding distance",
      "body": "Curated related: links (written at atom-creation time) and raw DBSCAN-discovered groups operate on separate signals. No reason they'd align. Two atoms with strong related: edge may be far in embedding space; two spatially close atoms may have no curated connection.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.85,
      "tags": [
        "clustering",
        "semantics",
        "embeddings",
        "related-links"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Concurrent ID-generation race in atom/cluster scripts",
      "body": "add_atom.py, add_cluster.py, add_source.py, migrate_atoms.py all use unguarded SELECT MAX(id)+1. Under parallel /harvest-knowledge sessions, two processes read same max before either commits; second insert hits PK collision. Requires atomic ID generation (autoincrement or transactional lock).",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "concurrency",
        "database",
        "race-condition",
        "id-generation"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Embedding re-computation blocks incremental clustering",
      "body": "embed_atoms.py re-embeds entire vault every run via Ollama with zero cache; has no concept of already-vectorized atoms. Blocks performance of frequent reconciliation passes. No persisted embedding store, content-hash gating, or incremental detection.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "embeddings",
        "performance",
        "caching",
        "ollama"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Use sqlite-vec for persistent embedding cache",
      "body": "Store embeddings in sqlite-vec vec0 virtual table, not plain BLOB. Enables future agent-facing ANN/cosine-search tools (not just internal caching). Supports content-hash gating to skip re-vectorizing unchanged atoms. Unlocks fast centroid recomputation and eps experiments without Ollama round-trips.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.9,
      "tags": [
        "sqlite-vec",
        "embeddings",
        "caching",
        "architecture",
        "ann-search"
      ],
      "promotion_target": "adr",
      "_window": 2
    },
    {
      "title": "Unify embed + reconcile into incremental loop",
      "body": "Consolidate embed_atoms.py + reconcile_vault.py into single pipeline: vectorize-and-cache, match all atoms to existing centroids first, flag only orphans for DBSCAN new-cluster discovery, re-sweep existing atoms against new centroids, repeat until convergence. Auto-apply high-confidence centroid matches; flag reassign/remove/merge for review.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.9,
      "tags": [
        "clustering",
        "pipeline",
        "architecture",
        "incremental",
        "centroid"
      ],
      "promotion_target": "adr",
      "_window": 2
    },
    {
      "title": "Concurrent harvest sessions require atomic ID generation",
      "body": "Multiple /harvest-knowledge sessions run in parallel, each writing atoms simultaneously. Design must prevent PK collisions under concurrent inserts. Blocks simple SELECT MAX(id)+1 pattern; requires autoincrement or transactional lock on ID generation.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.9,
      "tags": [
        "concurrency",
        "constraints",
        "harvest",
        "atoms",
        "id-generation"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Include legacy atom format upgrade in redesign",
      "body": "Clustering redesign scope includes handling legacy atoms lacking proper frontmatter (no id, no links, wrong format everywhere). Upgrade to modern format, merge with near-duplicates, or remove low-quality/pure-duplicate atoms as part of one-time vault migration during pipeline consolidation.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.85,
      "tags": [
        "clustering",
        "atom-format",
        "legacy",
        "cleanup",
        "migration"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "103 clusters accumulated from separate batch runs, not one pass",
      "body": "Existing 103 cluster files span dates 2026-06-30 to present, accumulated from ~10 separate /harvest-knowledge runs (10-30 items each), not one full-vault DBSCAN pass. Result: real duplication — 3× \"8-Phase Memory Write\", 3× \"Async Fan-Out\", 3× \"Token Budget\", etc., same concepts split across runs because add_cluster.py upserts by exact name-string match only.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.9,
      "tags": [
        "clustering",
        "deduplication",
        "vault-state",
        "history"
      ],
      "promotion_target": "none",
      "_window": 2
    },
    {
      "title": "Subagents cannot call AskUserQuestion",
      "body": "Subagents spawned in this project's flow system cannot access AskUserQuestion tool. They must proceed autonomously or report status; the tool is unavailable in subagent contexts. When designing flow agents, include fallback logic for approval checkpoints.",
      "memory_type": "tool_quirk",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.8,
      "tags": [
        "subagents",
        "flow-system",
        "tool-limitations"
      ],
      "promotion_target": "none",
      "_window": 3
    },
    {
      "title": "Flow-state.env shared-state causes concurrent-flow conflicts",
      "body": ".flow/flow-state.env is single shared file for telemetry logging across concurrent flows (not pipeline control). Multiple concurrent flows can clobber each other's state entries; flow-state-write.py guards by refusing overwrites when another flow is active. Persistent architecture issue worth addressing in flow-system redesign.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.8,
      "tags": [
        "flow-state",
        "concurrency",
        "shared-state"
      ],
      "promotion_target": "note",
      "_window": 3
    },
    {
      "title": "Test only where risk is genuine",
      "body": "Create tests only for centroid math, sync thresholds, cache hit/miss, concurrent ID allocation. Skip CLI/globbing/writer integration. Reflects prioritization against implementation burden in knowledge-vault clustering work.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "testing",
        "strategy",
        "coverage"
      ],
      "promotion_target": "none",
      "_window": 4
    },
    {
      "title": "Best-of-N selection inflates similarity",
      "body": "Comparing candidates against 800+ atoms and selecting best match inflates similarity scores via extreme-value effect. Threshold 0.75 safe for additive cluster-membership decisions but risky for irreversible file deletions. Audit matched pairs before bulk merges.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.65,
      "tags": [
        "similarity",
        "statistics",
        "ml-risk",
        "thresholds"
      ],
      "promotion_target": "note",
      "_window": 4
    },
    {
      "title": "Safety classifier blocks destructive ops",
      "body": "Claude Code auto-mode safety system identifies 'Irreversible Local Destruction' and requires explicit user authorization, even for logically-sound deletions/merges. Conservative protection; may require override for known-safe operations.",
      "memory_type": "tool_quirk",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "claude-code",
        "safety",
        "destructive-ops"
      ],
      "promotion_target": "none",
      "_window": 4
    },
    {
      "title": "Similarity thresholds fail in consistent-vocabulary domains",
      "body": "Domains with shared core terminology (AI/ML, agent systems) inflate similarity scores across all documents, making pure thresholds ineffective for deduplication. Tested at 0.878: 29 false positives, 1 false negative missed. Overlapping ranges (0.83–1.0 real duplicates, 0.80–0.92 noise) cannot be separated by threshold alone. Requires evidence-based signals (shared membership, co-occurrence).",
      "memory_type": "insight",
      "scope": "shared",
      "decay_class": "stable",
      "confidence": 1,
      "tags": [
        "clustering",
        "similarity-threshold",
        "false-positives",
        "vocabulary"
      ],
      "promotion_target": "best_practice",
      "_window": 5
    },
    {
      "title": "Transitive chaining falsely merges unrelated clusters in graph deduplication",
      "body": "Deduplication via transitive closure (A≈B, B≈C → merge A,B,C) falsely merges distinct concepts when bridged through hub clusters that legitimately touch multiple topics. Safe only for true cliques (all pairwise pairs directly evidenced). Example: 8-cluster group connected via 'Agent Role Archetypes' merged unrelated concepts (context loading, retrieval normalization, role vocabularies) that were genuinely separate.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 1,
      "tags": [
        "clustering",
        "transitive-chains",
        "clique-detection",
        "false-merges"
      ],
      "promotion_target": "note",
      "_window": 5
    },
    {
      "title": "Shared cluster membership: only reliable deduplication signal",
      "body": "Checking whether duplicate-candidate clusters share atoms (shared_members field) provides zero false positives and false negatives across 663 real-world candidates. Pure similarity is unreliable in consistent-domain vocabularies. Authoritative deduplication signal: atoms physically appearing in both clusters, verified via direct membership inspection, not scoring.",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 1,
      "tags": [
        "clustering",
        "deduplication",
        "shared-members",
        "evidence-based"
      ],
      "promotion_target": "adr",
      "_window": 5
    },
    {
      "title": "Windows case-insensitive filesystem orphans database records on capitalization-only collisions",
      "body": "Database records differing only in capitalization (e.g., Phase-level vs Phase-Level Rollback) both map to the same Windows filesystem file, orphaning the secondary DB row with no backing file. Filesystem is case-insensitive; database tracks as distinct entities, creating mismatch.",
      "memory_type": "tool_quirk",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 1,
      "tags": [
        "windows",
        "case-sensitivity",
        "filesystem",
        "database-mismatch"
      ],
      "promotion_target": "note",
      "_window": 5
    },
    {
      "title": "Header-parsing fragility from exact-string matching",
      "body": "Exact-string header matching in freeform frontmatter parsers fails silently across casing/wording variants. The upgrade_legacy_atoms.py parser only recognized lowercase `## What it is` / `## Why it matters` but real legacy atoms used title case `## What It Is` / `## Problem It Solves`, causing 26 of 54 atoms' content to be silently destroyed (replaced with empty body, frontmatter/ID intact). Solution: use case-insensitive matching + alias dictionaries (_HEADING_FIELD_ALIASES) so is_legacy() and parse_freeform() normalize consistently. Prevents same parser from drifting between detection and extraction logic.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.95,
      "tags": [
        "header-parsing",
        "frontmatter",
        "case-sensitivity",
        "aliasing",
        "silent-failure"
      ],
      "promotion_target": "best_practice",
      "_window": 6
    },
    {
      "title": "Debug silent content loss via immediate git diff",
      "body": "When bulk file rewrites report success but content appears truncated/missing, immediately diff affected files against `git HEAD` to quantify and isolate the damage before attempting recovery. This session caught 26 content losses by diffing git originals; enabled targeted parser fix and selective re-processing without manual recovery. Works because git HEAD captures the original state before any buggy transformation. Essential for destructive bulk operations where the bug can cause data loss at scale.",
      "memory_type": "insight",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.95,
      "tags": [
        "debugging",
        "git",
        "bulk-operations",
        "content-loss",
        "recovery"
      ],
      "promotion_target": "best_practice",
      "_window": 6
    },
    {
      "title": "Concurrent UPDATE paths need write-lock protection",
      "body": "The id_alloc.write_txn(BEGIN IMMEDIATE) concurrency fix was applied only to INSERT paths (new-atom creation) but not UPDATE paths (same-atom name collisions). UPDATE operations in add_atom.py, add_cluster.py etc. still do unprotected read-then-commit on existing rows — exactly the concurrent-write race this feature was built to prevent. All write paths (INSERT, UPDATE, MERGE) must use the same locking strategy or the bug class remains unfixed on half the code paths.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.95,
      "tags": [
        "concurrency",
        "sqlite",
        "begin-immediate",
        "id-alloc",
        "update"
      ],
      "promotion_target": "adr",
      "_window": 6
    },
    {
      "title": "Lock-scope consistency across writer scripts",
      "body": "add_atom.py (new-atom path) holds SQLite write lock across both file I/O and schema updates, while add_cluster.py releases the lock before file I/O. Same PR, same architecture.md template, divergent implementations. Lock-scope (what operations execute inside `with write_txn(conn):` vs. after) must be uniform across all writer scripts (add_atom, add_cluster, add_source, migrate_atoms) so future maintainers follow a consistent pattern. Either both include file-I/O inside the lock (harmless, slightly pessimistic locking) or both move it outside (optimized, matches architecture rationale).",
      "memory_type": "decision",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.85,
      "tags": [
        "lock-scope",
        "sqlite",
        "consistency",
        "write-lock",
        "file-io"
      ],
      "promotion_target": "adr",
      "_window": 6
    },
    {
      "title": "Regression test for header-parsing case variants",
      "body": "After fixing parse_freeform to use case-insensitive header matching + aliases, the regression test (test_upgrade_legacy_atoms.py::test_is_legacy_true_for_freeform_headers) must verify BOTH exact-cased AND title-cased header variants are recognized. The original bug arose because is_legacy() used exact-string matching while parse_freeform silently failed on non-matching casing. Test both detection paths with both casing variants to prevent the parser functions from drifting out of sync again in future refactors.",
      "memory_type": "correction",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.9,
      "tags": [
        "testing",
        "regression",
        "header-parsing",
        "case-variants",
        "drift-prevention"
      ],
      "promotion_target": "recipe",
      "_window": 6
    },
    {
      "title": "Acceptance-proof tasks for destructive bulk operations",
      "body": "Large destructive operations (live-vault cluster merges, legacy atom upgrades) must have explicit acceptance-proof tasks in execution-state.json that track whether the destructive apply actually ran against real data. Code passing unit tests is distinct from the feature passing acceptance against live data. If these tasks remain 'partial' when code is ready to merge, it signals the feature has not been validated end-to-end — either complete the destructive runs or explicitly descope them to a follow-up work order before merge.",
      "memory_type": "convention",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.8,
      "tags": [
        "acceptance-testing",
        "destructive-ops",
        "live-data",
        "execution-state",
        "workflow"
      ],
      "promotion_target": "note",
      "_window": 6
    },
    {
      "title": "stale_related field regression in sync_clusters reconcile-report",
      "body": "When sync_clusters() refactored to use _match_existing with `atom_related={}` (documented limitation: 'stale_related will always be empty'), the reconcile-report.json's stale_related field went unpopulated. This regresses visibility for downstream agents (cluster-reconciler) that depend on stale-link flags. Architecture.md documents reconcile_vault.score_atoms_vs_clusters as populating all fields unchanged, but sync() now violates this contract silently. Either fix by threading real atom_related through sync() or explicitly note the tradeoff in architecture.md's Decisions section.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.9,
      "tags": [
        "reconcile-report",
        "stale-related",
        "sync-clusters",
        "atom-related",
        "regression"
      ],
      "promotion_target": "note",
      "_window": 6
    },
    {
      "title": "Deduplicate shared constants to prevent drift",
      "body": "When alias maps or normalization functions are duplicated across functions (e.g., _HEADING_FIELD_ALIASES in is_legacy and parse_freeform), they drift over time as maintenance fixes one but not the other, causing silent bugs. Move to module top, reference once. Prevents this entire class of divergence bug.",
      "memory_type": "convention",
      "scope": "global",
      "decay_class": "architecture",
      "confidence": 0.95,
      "tags": [
        "deduplication",
        "single-source-of-truth",
        "maintenance",
        "constants"
      ],
      "promotion_target": "best_practice",
      "_window": 7
    },
    {
      "title": "Avoid hardcoded mock data in production code paths",
      "body": "Hardcoding empty dicts or test doubles (e.g., {} for atom_related) instead of loading real data from actual sources creates regressions that hide until integration testing. Always thread real data through; mock/empty structs should only appear in test fixtures or behind feature flags.",
      "memory_type": "failure",
      "scope": "global",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "mock-data",
        "hardcoding",
        "regression",
        "testing"
      ],
      "promotion_target": "best_practice",
      "_window": 7
    },
    {
      "title": "Argparse treats missing optional args as None, not []",
      "body": "When no instances of an optional flag (e.g., --scope) are provided to argparse, args.scope becomes None instead of an empty list. This breaks empty-set semantics (no-op should stay no-op, full-vault should not be the default). Guard with explicit check before looping/iterating.",
      "memory_type": "tool_quirk",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "argparse",
        "edge-cases",
        "optional-arguments",
        "cli"
      ],
      "promotion_target": "recipe",
      "_window": 7
    },
    {
      "title": "Wrap database UPDATEs in write_txn for race safety",
      "body": "UPDATE paths must be inside write_txn context manager; aligns lock-scope and prevents races where the SELECT-then-UPDATE can diverge. Established pattern in add_cluster.py; apply consistently to all UPDATE operations (add_atom.py, similar scripts).",
      "memory_type": "convention",
      "scope": "project",
      "decay_class": "architecture",
      "confidence": 0.85,
      "tags": [
        "database",
        "transactions",
        "race-conditions",
        "consistency"
      ],
      "promotion_target": "none",
      "_window": 7
    },
    {
      "title": "add_atom/add_cluster UPDATE paths require write_txn",
      "body": "add_atom.write_atom and add_cluster.add_cluster UPDATE paths had zero write_txn protection, enabling lost-update race on concurrent writes. Both now wrapped in write_txn. Pattern: SQLite UPDATE to same row needs serialization to prevent silent data loss.",
      "memory_type": "correction",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.95,
      "tags": [
        "concurrency",
        "sqlite",
        "write_txn",
        "lost-update"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "is_legacy/parse_freeform heading-alias consistency",
      "body": "is_legacy and parse_freeform independently maintained heading-alias mappings, risking silent divergence. Unified to single shared alias map to prevent future drift.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.9,
      "tags": [
        "alias-mapping",
        "state-drift",
        "fragility"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "harvest-knowledge Phase 4B empty-scope cascading",
      "body": "harvest-knowledge.md Phase 4B had no guard for empty scope, silently triggering full-vault sync instead of no-op. Added explicit guard condition to prevent cascading.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.8,
      "tags": [
        "harvest",
        "edge-case",
        "guard-condition"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "sync_clusters.py stale_related data wiring",
      "body": "sync_clusters.stale_related was always empty, a regression vs. original reconcile_vault.py. Fixed by threading real atom_related data through the pipeline.",
      "memory_type": "failure",
      "scope": "project",
      "decay_class": "implementation",
      "confidence": 0.9,
      "tags": [
        "regression",
        "stale_related",
        "data-wiring"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "execution-state.json tracking vs. implementation",
      "body": "execution-state.json task status can diverge from actual implementation (e.g., tasks marked done but never implemented). Requires periodic validation against codebase to catch silent regressions.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.85,
      "tags": [
        "tracking",
        "execution-state",
        "validation"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "embed_cache.knn vec0 MATCH semantics",
      "body": "embed_cache.knn uses vec0's MATCH ordering (euclidean). For L2-normalized vectors, euclidean distance is mathematically equivalent to cosine similarity, so ranking matches cosine recommendations.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "api_contract",
      "confidence": 0.95,
      "tags": [
        "vec0",
        "knn",
        "embedding",
        "distance-metric"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "Merge orchestrator requires explicit user confirmation",
      "body": "Merge-feature orchestrator correctly declined to interpret coordinator-relayed 'approval' as authorization for git actions. Orchestrators require direct user instruction, not nested relayed signals.",
      "memory_type": "tool_quirk",
      "scope": "global",
      "decay_class": "stable",
      "confidence": 0.9,
      "tags": [
        "orchestrator",
        "authorization",
        "claude-code"
      ],
      "promotion_target": "none",
      "_window": 8
    },
    {
      "title": "Explicit change descriptions for doc-sync",
      "body": "When calling /update-project-docs for complex changes spanning multiple files/components, provide an explicit, detailed description instead of relying on git diff auto-detection. Doc-sync can misclassify which docs (ADRs, DDRs, notes) are affected without clear context, resulting in incorrect routing and incomplete updates.",
      "memory_type": "insight",
      "scope": "project",
      "decay_class": "stable",
      "confidence": 0.6,
      "tags": [
        "doc-sync",
        "documentation"
      ],
      "promotion_target": "none",
      "_window": 9
    }
  ]
}