get-claudia 1.56.1 → 1.58.0

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to Claudia will be documented in this file.
 
+## 1.58.0 (2026-05-13)
+
+### The Memory Reliability Release
+
+Five PRs that fix the memory layer's biggest recurring failure mode and lock in the integration philosophy. After this release, memory writes that name entities ("Matt Blumberg") actually create those entities with the correct type. The release history's recurring memory-fix releases ("Recall Recovery", "Vector Search Fix", "Semantic Search Actually Works Now") get permanent regression-test sentinels so the same bug classes can't quietly come back. And the codebase loses a dual-maintenance hazard that was already costing time.
+
+#### Fixed
+- **`memory_remember` actually links entities and infers their type correctly (#54)** -- A confirmed bug from 2026-05-13: calling `memory_remember(content="Matt Blumberg said X", entities=["Matt Blumberg", "Markup AI"])` was creating entities but assigning them `type: person` by default, even when the name clearly indicated an organization. "Markup AI" was being saved as a person. The real bug was in `_infer_entity_type` -- it didn't recognise `AI` / `.ai` / `Co.` as corporate suffixes and fell back to `person`. Fixed with a pure-function rule-based type inference (corporate suffixes -> organization, project keywords -> project, person patterns -> person, fallback -> concept, never default to person). Plus a new `claudia-memory --backfill-entities` CLI to retroactively link orphaned references in existing user databases.
+
+#### Added
+- **`claudia memory backfill-entities` command (#54)** -- Default dry-run: prints a plan and writes nothing. `--apply` makes a timestamped backup to `~/.claudia/backups/memory-{timestamp}.db` first, then applies the backfill. Idempotent: re-running on an already-backfilled DB is a no-op. Aborts cleanly if backup creation fails.
+- **5 regression tests for recurring bug classes (#56)** -- New `memory-daemon/tests/test_recurring_regressions.py` adds permanent forward-looking sentinels for: entity linking on `memory_remember`, recall returning results after seed writes, embedding migration preserving recall, daemon startup tolerating stale SHM files, and `memory_briefing` returning a valid structure on an empty database. Each test docstring names the historical releases where its bug class appeared (v1.35.x, v1.51.5, v1.51.18, v1.55.7, v1.55.8, v1.55.14, v1.21.1, v1.40.1).
+- **API parameter aliases for read-side MCP tools (#57)** -- `memory_about` now accepts `entity_name` and `name` alongside `entity`. `memory_relate` accepts `source_entity` / `target_entity` / `relationship_type` alongside `source` / `target` / `relationship`. `memory_recall` accepts `q` and `search` alongside `query`. Purely additive: every existing caller continues to work unchanged. Aliases normalize at the MCP boundary; service-layer signatures are untouched. If both canonical and alias are passed in the same call, canonical wins.
+
+#### Removed
+- **Rube (Composio) MCP integration as a bundled default (#41)** -- Rube is no longer a recommended or bundled MCP server in `.mcp.json.example` (root and template-v2), README, or the Claudia documentation. Locks in the direct-integrations-only philosophy (claude.ai-native MCPs + user-built custom MCPs like Gmail/Calendar). Existing users with `rube` already configured continue to work unchanged; the installer simply no longer ships Rube as an example. The "Tool configuration" example in `claudia-principles.md` was updated to vendor-neutral phrasing.
+- **Legacy `claudia/` sibling files (#55)** -- Removed 3 stale sibling files (`post-tool-capture.py`, `session-health-check.py`, `settings.local.json`) that lived under `claudia/`. These were never reaching users (the installer ships from `template-v2/` only), but every hook bug fix had to remember to patch both locations. The dual-maintenance hazard was real: PR #38's sibling-fix step had to apply the same env-var fix twice. Removed at the source.
+
+#### Stats
+- **43 new tests** across 4 files (22 entity-resolution tests in #54, 5 regression sentinels in #56, 16 alias tests in #57)
+- **805 total daemon tests passing** (up from 762 before the v1.57.0 chain), 0 regressions
+- TDD sensitivity proofs for every behavior change: tests fail on the un-modified code, pass after the fix
+- 5 PRs merged, all with stop-gates and TDD discipline
+
+#### Notes
+- The bug in #54 was different from the original proposal (#51) described. The proposal said "entities are silently ignored." Actually the entity *records* were getting created -- the bug was that they were all getting `type: person`. Fixing the actual bug rather than the imagined one was a better outcome.
+- The `claudia memory backfill-entities` command surface lives on the daemon's argparse (alongside `--backfill-embeddings`, `--migrate-vault-para`), not as a `claudia memory ...` subcommand on the Node CLI. The Node CLI is the installer, not a memory-command dispatcher.
+- Aliases are NOT yet advertised in the MCP `list_tools()` `inputSchema`. They are tolerantly accepted at the request boundary. Schema-level advertisement is a future enhancement if it proves needed for client discoverability.
+
+---
+
+## 1.57.0 (2026-05-13)
+
+### The Curated Memory Release
+
+Five PRs that complete one thesis: **curated, judgment-driven memory capture, enforced at prompt time and persisted across sessions.** Claudia now catches the user's intent when it matters, persists canonical facts as they emerge, and writes a daily session summary so context survives across days.
+
+#### Fixed
+- **PostToolUse hook actually runs (#38)** -- The hook was reading `os.environ.get("CLAUDE_TOOL_NAME")`, which Claude Code never sets. Every install since the hook landed had been silently no-op'ing, so `~/.claudia/observations.jsonl` was never written. The hook now reads its payload from stdin per the documented hook contract. Includes a sibling fix to the legacy `claudia/.claude/hooks/post-tool-capture.py` for codebase consistency.
+
+#### Added
+- **Memory-commitment rule (#39)** -- A new always-active rule (`template-v2/.claude/rules/memory-commitment.md`) codifies when to save canonical facts immediately via `memory_remember` / `memory_batch` rather than batching to end-of-session reflection. Trigger phrases include "lock this in," "remember this," "this is canonical." Substantive-artifact discipline: at the end of producing a multi-file artifact, do a memory commitment pass and save the canonical facts as one bundled `memory_batch` call.
+- **UserPromptSubmit hook with intent detection (#42)** -- A new hook (`template-v2/.claude/hooks/user-prompt-capture.py`) inspects the user's prompt at submit time and injects reminder context for two trigger classes. Class 1: canonical-fact phrases ("lock this in," "remember this," etc.) tell the agent to save immediately rather than wait for `/meditate`. Class 2: destructive command patterns (`rm -rf`, `git push --force`, `DROP TABLE`, etc.) trigger a "verify before acting" reminder per the safety-first principle. Destructive patterns are surfaced to the model as human-readable labels (`rm -rf (recursive delete)`), not raw regex, so the agent can reason about them clearly.
+- **Daily session summary system (#40)** -- A new SessionEnd hook (`template-v2/.claude/hooks/session-summary.py`) writes a per-session markdown summary to `~/.claudia/sessions/YYYY-MM-DD/NN-slug.md` covering opening prompt, files touched, external actions, and find-this-again references. SessionStart now surfaces a 3-day digest of recent sessions via the existing health-check hook, so future-Claudia knows what past-Claudia worked on. PostToolUse hook gained `file_path` extraction for Write/Edit/MultiEdit/NotebookEdit and `external_action` labels for git push, gh repo create, vercel/netlify deploy, supabase db push, and direct MCP sends.
+- **Explicit upgrade messaging (#50)** -- The installer now names `~/.claudia/` explicitly after an upgrade and lists what is preserved (entities, relationships, reflections, embeddings) instead of the generic "data preserved" phrasing. Users care about their accumulated memory graph; the previous wording did not signal that the database is safe.
+
+#### Changed
+- **External-action detection uses word-boundary regex (#40)** -- Previously a substring match, so `echo "git push for testing"` falsely fired the `external_action` flag. The new patterns anchor on command separators (line start, `;`, `&&`, `|`, `(`) and skip transparent prefixes (`sudo`, `nohup`, `time`, `env`). False positives on echoed/quoted strings are eliminated; real commands still fire.
+- **PostToolUse output truncation 200 -> 300 chars (#40)** -- Room for the richer output context that includes `file_path` and `external_action` labels alongside the truncated stdout/stderr.
+
+#### Stats
+- 41 new hook tests in `tests/hooks/` (stdlib `unittest`, zero new dependencies), all passing in ~1.5s
+- TDD sensitivity proofs for every behavior change: tests fail on the un-modified hook, pass after the fix
+- 5 PRs merged, 0 regressions
+
+#### Notes
+- The brief that drove this chain emphasized one principle: **trust the existing user-file preservation policy (commit `efce9f2`)** rather than inventing a new upgrade framework. The installer's behavior didn't change; only the messaging did.
+- The four hook PRs each landed with their own automated tests and TDD sensitivity proofs. The legacy `claudia/` subdirectory was kept in sync with the canonical `template-v2/` to avoid maintenance drift.
+
+---
+
 ## 1.56.1 (2026-04-11)
 
 ### Preserve User-Modified Skills on Upgrade

package/README.md

@@ -320,19 +320,6 @@ This generates a one-click URL to enable all required Google APIs and walks you
 | **Extended** | 83 | Core + Docs, Sheets, Tasks, Chat |
 | **Complete** | 111 | Extended + Slides, Forms, Apps Script |
 
-### 500+ Apps via Rube
-
-[Rube](https://rube.app) (by Composio) connects Claudia to Slack, Notion, Jira, GitHub, Linear, HubSpot, Stripe, Figma, and hundreds more through one-click OAuth. No per-app MCP setup needed.
-
-| Category | Examples |
-|----------|----------|
-| **Communication** | Slack, Discord, Teams, Telegram |
-| **Project Management** | Jira, Linear, Asana, Trello, Monday.com |
-| **Knowledge & Docs** | Notion, Confluence, Google Docs, Coda |
-| **Code & Dev** | GitHub, GitLab, Bitbucket |
-| **CRM & Sales** | HubSpot, Salesforce, Pipedrive |
-| **And 500+ more** | [Browse the full list](https://rube.app) |
-
 ### Obsidian Vault
 
 Memory auto-syncs to an Obsidian vault at `~/.claudia/vault/` using PARA structure. Every entity becomes a markdown note with `[[wikilinks]]`, so Obsidian's graph view maps your network. SQLite is the source of truth; the vault is a read-only projection you can browse and search.

package/bin/index.js

@@ -877,7 +877,10 @@ async function main() {
     }
 
     console.log('');
-    console.log(` ${colors.cyan}✓${colors.reset} Framework updated (data preserved)`);
+    console.log(` ${colors.cyan}✓${colors.reset} Framework updated`);
+    console.log(`   • Your memory at ${colors.bold}~/.claudia/${colors.reset} is preserved (entities, relationships, reflections, embeddings).`);
+    console.log(`   • Skills and hooks refreshed; any modifications you chose to keep were respected.`);
+    console.log(`   • Restart Claude Code for changes to take effect.`);
   }
 
   // Self-heal: strip CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS from settings (#24)

package/memory-daemon/claudia_memory/__main__.py

@@ -1110,6 +1110,24 @@ def main():
         action="store_true",
         help="Preview mode for --migrate-vault-para: show routing plan without making changes",
     )
+    parser.add_argument(
+        "--backfill-entities",
+        action="store_true",
+        help=(
+            "Scan memories for un-linked entity references and propose "
+            "creating/linking them (Proposal #51). Dry-run by default; "
+            "pass --apply to write changes (creates a SQLite backup first)."
+        ),
+    )
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help=(
+            "With --backfill-entities: actually write the changes. "
+            "A SQLite backup is created at ~/.claudia/backups/ before any "
+            "writes; if backup creation fails, the command aborts."
+        ),
+    )
     parser.add_argument(
         "--migrate-legacy",
         action="store_true",
@@ -1704,6 +1722,61 @@ def main():
         run_para_migration(vault_path, db=db, preview=args.preview)
         return
 
+    if args.backfill_entities:
+        # Entity-link backfill (Proposal #51). Dry-run by default; --apply
+        # writes after creating a SQLite backup.
+        setup_logging(debug=args.debug)
+        from datetime import datetime as _dt
+
+        from .services.backfill import (
+            apply_backfill,
+            format_plan_summary,
+            plan_backfill,
+        )
+
+        db = get_db()
+        db.initialize()
+
+        plan = plan_backfill(db)
+        print(format_plan_summary(plan))
+
+        if not args.apply:
+            # Dry-run path: we already printed the plan; nothing more to do.
+            return
+
+        # --apply: take the mandatory backup first.
+        config = get_config()
+        backups_dir = Path(config.backup_dir)
+        try:
+            backups_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            print(
+                f"\nCannot create backup directory {backups_dir}: {e}\n"
+                "Aborting before any database writes."
+            )
+            sys.exit(1)
+
+        timestamp = _dt.utcnow().strftime("%Y-%m-%dT%H%M%SZ")
+        backup_path = backups_dir / f"memory-{timestamp}.db"
+
+        try:
+            result = apply_backfill(db, plan, backup_path=backup_path)
+        except Exception as e:
+            print(
+                f"\nBackfill aborted (no DB writes performed): {e}\n"
+                f"Backup target was: {backup_path}"
+            )
+            sys.exit(1)
+
+        print(
+            "\nBackfill applied:\n"
+            f"  backup written to:   {result.backup_path}\n"
+            f"  entities created:    {result.entities_created}\n"
+            f"  entities reused:     {result.entities_reused}\n"
+            f"  memory_entities links created: {result.links_created}"
+        )
+        return
+
     if args.merge_databases:
         # Manual consolidation of hash-named databases
         setup_logging(debug=args.debug)

package/memory-daemon/claudia_memory/mcp/server.py

@@ -141,6 +141,79 @@ def _require(arguments: dict, key: str, tool_name: str):
     return value
 
 
+# ── Parameter-name aliases (v1.58.0 PR E) ──
+#
+# The memory MCP tools historically used different parameter conventions
+# (entity vs source/target/relationship vs query). The aliases below let
+# callers use a consistent variant while every existing caller continues
+# to work unchanged. Normalization happens here at the MCP boundary;
+# service-layer signatures in claudia_memory/services/ are untouched.
+#
+# Rules:
+#   1. Purely additive. The canonical name continues to work as before.
+#   2. If both the canonical name and an alias are provided in the same
+#      call, the canonical name wins (the alias is left in place and is
+#      not consulted by the handler).
+#   3. Otherwise, the first matching alias is renamed to the canonical
+#      key and the alias key is removed from the arguments dict so the
+#      handler only ever sees the canonical name.
+
+_PARAM_ALIASES: Dict[str, Dict[str, List[str]]] = {
+    "memory_about": {
+        "entity": ["entity_name", "name"],
+    },
+    "memory_relate": {
+        "source": ["source_entity"],
+        "target": ["target_entity"],
+        "relationship": ["relationship_type"],
+    },
+    "memory_recall": {
+        "query": ["q", "search"],
+    },
+}
+
+
+def _normalize_params(arguments: dict, canonical: str, aliases: List[str]) -> dict:
+    """Resolve alias parameter names to the canonical name.
+
+    If the canonical name is already present in `arguments`, it wins and
+    `arguments` is returned unchanged. Otherwise, the first alias from
+    `aliases` that is present is renamed to the canonical key, and the
+    alias key is removed. If no alias matches either, `arguments` is
+    returned unchanged.
+
+    The function never mutates the caller's dict: when a rewrite is
+    needed it returns a shallow copy with the alias key replaced.
+    """
+    if canonical in arguments:
+        return arguments
+    for alias in aliases:
+        if alias in arguments:
+            arguments = dict(arguments)
+            arguments[canonical] = arguments.pop(alias)
+            return arguments
+    return arguments
+
+
+def _apply_parameter_aliases(tool_name: str, arguments: dict) -> dict:
+    """Apply all registered aliases for the given tool, if any.
+
+    Tools without an entry in `_PARAM_ALIASES` (the vast majority) get
+    their arguments back unchanged. Dot-notation aliases (e.g.
+    'memory.about') are routed to the same canonical tool name for the
+    purposes of alias lookup.
+    """
+    # Dot-notation aliases (memory.about, etc.) share the same canonical
+    # alias map as their underscore counterparts.
+    lookup_name = tool_name.replace(".", "_", 1) if "." in tool_name else tool_name
+    aliases_for_tool = _PARAM_ALIASES.get(lookup_name)
+    if not aliases_for_tool:
+        return arguments
+    for canonical, alias_list in aliases_for_tool.items():
+        arguments = _normalize_params(arguments, canonical, alias_list)
+    return arguments
+
+
 MAX_RESPONSE_BYTES = 50_000
 
 
@@ -3142,6 +3215,10 @@ async def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:
     """Handle tool calls via dispatch registry."""
     db = get_db()
     try:
+        # Normalize parameter-name aliases at the MCP boundary so handlers
+        # only ever see canonical parameter names. Purely additive: tools
+        # without registered aliases are unchanged. See _PARAM_ALIASES.
+        arguments = _apply_parameter_aliases(name, arguments)
         with db.transaction():
             handler = _TOOL_HANDLERS.get(name)
             if handler:

package/memory-daemon/claudia_memory/services/backfill.py

@@ -0,0 +1,346 @@
+"""Entity-link backfill command (Proposal #51).
+
+The pre-v1.58 write path linked entities to memories *most* of the time
+but auto-created organisations as type=person and could miss entities
+referenced only in the content (no ``about_entities`` array supplied).
+
+This module scans existing memories that have no entity links and
+proposes new entity creations + ``memory_entities`` rows. Two phases:
+
+* ``plan_backfill(db)`` -- pure read. Returns a :class:`BackfillPlan`
+  with everything it would do. No writes.
+* ``apply_backfill(db, plan, backup_path)`` -- writes. **First** creates
+  a SQLite backup at ``backup_path``. If backup fails, raises BEFORE
+  any DB modification.
+
+CLI entry points live in ``claudia_memory/__main__.py``:
+``claudia-memory --backfill-entities`` (dry-run; default) and
+``claudia-memory --backfill-entities --apply``.
+
+No new deps. No schema migrations. Idempotent on re-apply.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .entities import infer_entity_type
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Plan / Result dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BackfillPlan:
+    """Read-only plan of what apply_backfill would do.
+
+    Attributes:
+        orphan_count: number of memory rows with zero memory_entities links
+            that the planner thinks SHOULD have at least one link.
+        proposed_entities: list of dicts ``{"name": str, "inferred_type":
+            str, "memory_ids": [int, ...]}``. Each dict represents a name
+            we detected in memory content for which we will (a) create the
+            entity if missing, (b) link it to those memories.
+        scanned_memories: total memories the planner looked at.
+    """
+
+    orphan_count: int = 0
+    proposed_entities: List[Dict[str, Any]] = field(default_factory=list)
+    scanned_memories: int = 0
+
+
+@dataclass
+class BackfillResult:
+    """Counts of writes performed by apply_backfill."""
+
+    entities_created: int = 0
+    entities_reused: int = 0
+    links_created: int = 0
+    backup_path: Optional[Path] = None
+
+
+# ---------------------------------------------------------------------------
+# Name detection -- intentionally conservative
+# ---------------------------------------------------------------------------
+
+# Two or more capitalised words: a reasonable signal for proper nouns.
+# We won't catch single-word entities like "Acme" here -- that prevents a
+# flood of false positives like "The", "She", "Monday" at sentence starts.
+_PROPER_NOUN_RE = re.compile(r"\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\b")
+
+# Things we never want to propose as entity names.
+_STOPWORDS = frozenset(
+    {
+        "Project",  # Without a following noun, this is the keyword itself.
+        "Inc",
+        "LLC",
+        "Corp",
+        "AI",
+        "Ltd",
+        "Co",
+    }
+)
+
+
+def _candidate_names(content: str) -> List[str]:
+    """Extract proper-noun candidate names from memory content.
+
+    Returns a list of unique, order-preserved candidates.
+    """
+    if not content:
+        return []
+
+    seen: Dict[str, None] = {}
+    for match in _PROPER_NOUN_RE.finditer(content):
+        raw = match.group(1).strip()
+        # Reject single-token stopwords we accidentally captured.
+        if raw in _STOPWORDS:
+            continue
+        seen.setdefault(raw, None)
+    return list(seen.keys())
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: plan_backfill (NO writes)
+# ---------------------------------------------------------------------------
+
+
+def plan_backfill(db) -> BackfillPlan:
+    """Scan memories with no entity links and propose new links.
+
+    Args:
+        db: The Database object (sqlite wrapper).
+
+    Returns:
+        A :class:`BackfillPlan`. The caller can inspect ``orphan_count``
+        and ``proposed_entities`` before deciding to ``--apply``.
+
+    This function MUST NOT write to the database. Tests assert this.
+    """
+    plan = BackfillPlan()
+
+    # Find memories that have no entity link at all and have content
+    # that looks like it mentions someone or something.
+    rows = db.execute(
+        """
+        SELECT m.id, m.content
+        FROM memories m
+        LEFT JOIN memory_entities me ON m.id = me.memory_id
+        WHERE me.memory_id IS NULL
+          AND m.invalidated_at IS NULL
+          AND m.content IS NOT NULL
+        """,
+        fetch=True,
+    ) or []
+
+    plan.scanned_memories = len(rows)
+    if not rows:
+        return plan
+
+    # name -> {"inferred_type": str, "memory_ids": [int]}
+    by_name: Dict[str, Dict[str, Any]] = {}
+
+    for row in rows:
+        memory_id = row["id"]
+        content = row["content"]
+        names = _candidate_names(content)
+        if not names:
+            continue
+        plan.orphan_count += 1
+        for name in names:
+            entry = by_name.setdefault(
+                name,
+                {
+                    "name": name,
+                    "inferred_type": infer_entity_type(name, content),
+                    "memory_ids": [],
+                },
+            )
+            entry["memory_ids"].append(memory_id)
+
+    plan.proposed_entities = list(by_name.values())
+    return plan
+
+
+# ---------------------------------------------------------------------------
+# Phase 2: apply_backfill (WRITES, but only after a successful backup)
+# ---------------------------------------------------------------------------
+
+
+def _create_backup(db, backup_path: Path) -> Path:
+    """Write a SQLite-native backup of ``db`` to ``backup_path``.
+
+    Uses :meth:`sqlite3.Connection.backup` for crash-consistent copy.
+    Creates parent directories. Raises on any failure so the caller can
+    abort the apply before touching the main DB.
+    """
+    backup_path = Path(backup_path)
+    backup_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # The Database wrapper exposes a thread-local connection via
+    # ``_get_connection``. We do not capture it as a long-lived
+    # attribute -- always ask the wrapper for the live one.
+    if hasattr(db, "_get_connection"):
+        source_conn = db._get_connection()  # noqa: SLF001
+    elif hasattr(db, "conn"):
+        source_conn = db.conn
+    else:
+        raise RuntimeError(
+            "Cannot create backup: db has no _get_connection or conn attribute"
+        )
+
+    target = sqlite3.connect(str(backup_path))
+    try:
+        source_conn.backup(target)
+    finally:
+        target.close()
+
+    if not backup_path.exists() or backup_path.stat().st_size == 0:
+        raise RuntimeError(f"Backup file at {backup_path} is missing or empty")
+
+    return backup_path
+
+
+def _ensure_entity_for_backfill(
+    db, name: str, entity_type: str
+) -> tuple[int, bool]:
+    """Return (entity_id, created_now).
+
+    Looks up by canonical_name (lowercased). Returns the existing id
+    if found, else inserts a new row. Does not touch embeddings (the
+    main daemon's normal flow will pick those up on next access).
+    """
+    canonical = name.lower().strip()
+    existing = db.get_one(
+        "entities",
+        where="canonical_name = ?",
+        where_params=(canonical,),
+    )
+    if existing:
+        return existing["id"], False
+
+    now = datetime.utcnow().isoformat()
+    new_id = db.insert(
+        "entities",
+        {
+            "name": name,
+            "type": entity_type,
+            "canonical_name": canonical,
+            "importance": 1.0,
+            "created_at": now,
+            "updated_at": now,
+        },
+    )
+    return new_id, True
+
+
+def apply_backfill(db, plan: BackfillPlan, backup_path: Path) -> BackfillResult:
+    """Apply the plan after first taking a SQLite backup.
+
+    Args:
+        db: Database wrapper.
+        plan: A :class:`BackfillPlan` from :func:`plan_backfill`.
+        backup_path: Where to write the SQLite backup. Required.
+
+    Returns:
+        A :class:`BackfillResult` with counts.
+
+    Raises:
+        Anything raised by :func:`_create_backup`. If the backup step
+        fails, NO writes are performed.
+    """
+    backup_path = Path(backup_path)
+
+    # Backup MUST come first. If it fails, abort before any DB write.
+    created_backup = _create_backup(db, backup_path)
+    logger.info("Backfill: backup created at %s", created_backup)
+
+    result = BackfillResult(backup_path=created_backup)
+
+    for proposal in plan.proposed_entities:
+        name = proposal["name"]
+        entity_type = proposal["inferred_type"]
+        memory_ids = proposal["memory_ids"]
+
+        entity_id, created_now = _ensure_entity_for_backfill(db, name, entity_type)
+        if created_now:
+            result.entities_created += 1
+        else:
+            result.entities_reused += 1
+
+        for memory_id in memory_ids:
+            try:
+                db.insert(
+                    "memory_entities",
+                    {
+                        "memory_id": memory_id,
+                        "entity_id": entity_id,
+                        "relationship": "about",
+                    },
+                )
+                result.links_created += 1
+            except Exception as e:
+                # Duplicate link (memory already has it) is harmless.
+                logger.debug(
+                    "Backfill: skipping duplicate link memory=%s entity=%s: %s",
+                    memory_id,
+                    entity_id,
+                    e,
+                )
+
+    logger.info(
+        "Backfill applied: %d entities created, %d reused, %d links",
+        result.entities_created,
+        result.entities_reused,
+        result.links_created,
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# CLI helper: render a plan summary for the dry-run output
+# ---------------------------------------------------------------------------
+
+
+def format_plan_summary(plan: BackfillPlan) -> str:
+    """Human-readable summary of a plan (printed in dry-run mode)."""
+    lines = [
+        "Entity-link backfill plan (dry-run, no writes):",
+        f"  Scanned memories without links: {plan.scanned_memories}",
+        f"  Memories with orphan name references: {plan.orphan_count}",
+        f"  Proposed new/linked entities: {len(plan.proposed_entities)}",
+    ]
+    if plan.proposed_entities:
+        lines.append("")
+        lines.append("  By inferred type:")
+        type_counts: Dict[str, int] = {}
+        for p in plan.proposed_entities:
+            type_counts[p["inferred_type"]] = (
+                type_counts.get(p["inferred_type"], 0) + 1
+            )
+        for t, n in sorted(type_counts.items()):
+            lines.append(f"    {t}: {n}")
+        # Show a small sample so the user can sanity-check.
+        sample = plan.proposed_entities[:10]
+        lines.append("")
+        lines.append("  Sample (first 10):")
+        for p in sample:
+            lines.append(
+                f"    - {p['name']!r} -> {p['inferred_type']} "
+                f"({len(p['memory_ids'])} memory link(s))"
+            )
+    lines.append("")
+    lines.append(
+        "Run with --apply to write changes. A SQLite backup will be created first."
+    )
+    return "\n".join(lines)