basic-memory 0.23.3.dev8__py3-none-any.whl → 0.24.0__py3-none-any.whl

basic_memory/__init__.py

@@ -1,7 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
 # Package version - updated by release automation
-__version__ = "0.23.2"
+__version__ = "0.24.0"
 
 # API version for FastAPI - independent of package version
 __api_version__ = "v2"

basic_memory/alembic/alembic.ini

@@ -28,7 +28,9 @@ prepend_sys_path = .
 
 # set to 'true' to run the environment during
 # the 'revision' command, regardless of autogenerate
-# revision_environment = false
+# Basic Memory: env.py assigns sequential revision IDs (migrations.assign_sequential_revision_ids),
+# so hand-written revisions must run it too, not only --autogenerate ones.
+revision_environment = true
 
 # set to 'true' to allow .pyc and .pyo files without
 # a source .py file to be detected as revisions in the

basic_memory/alembic/env.py

@@ -10,6 +10,7 @@ from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 
 from alembic import context
 
+from basic_memory.alembic.migrations import assign_sequential_revision_ids
 from basic_memory.config import ConfigManager
 
 # Constraint: never apply nest_asyncio here. It replaces asyncio.run and
@@ -88,6 +89,9 @@ def run_migrations_offline() -> None:
         dialect_opts={"paramstyle": "named"},
         include_object=include_object,
         render_as_batch=True,
+        # `alembic revision` (the `just migration` recipe) names each new revision by its
+        # schema version instead of a random ID; see migrations.LAST_UNNUMBERED_REVISION.
+        process_revision_directives=assign_sequential_revision_ids,
     )
 
     with context.begin_transaction():
@@ -102,6 +106,9 @@ def do_run_migrations(connection):
         include_object=include_object,
         render_as_batch=True,
         compare_type=True,
+        # `alembic revision` (the `just migration` recipe) names each new revision by its
+        # schema version instead of a random ID; see migrations.LAST_UNNUMBERED_REVISION.
+        process_revision_directives=assign_sequential_revision_ids,
     )
     with context.begin_transaction():
         context.run_migrations()

basic_memory/alembic/migrations.py

@@ -1,9 +1,23 @@
 """Functions for managing database migrations."""
 
 from pathlib import Path
-from loguru import logger
-from alembic.config import Config
+
 from alembic import command
+from alembic.config import Config
+from alembic.operations.ops import MigrationScript
+from alembic.runtime.migration import MigrationContext
+from alembic.script import ScriptDirectory
+from loguru import logger
+
+# --- Sequential revision IDs ---
+# Revisions up to and including this one carry unnumbered IDs: some are random hex from
+# Alembic, many were hand-picked (z9a0b1c2d3e4 itself is not hex). Every revision after it
+# is named by its schema version, zero-padded to four digits: "0040" revises
+# "z9a0b1c2d3e4", "0041" revises "0040". A version number orders schemas at a glance
+# (cloud tenants report which one they run), where an unnumbered ID only says "different".
+# The padding keeps migration files in version order in a directory listing.
+LAST_UNNUMBERED_REVISION = "z9a0b1c2d3e4"
+REVISION_ID_DIGITS = 4
 
 
 def get_alembic_config() -> Config:  # pragma: no cover
@@ -16,6 +30,76 @@ def get_alembic_config() -> Config:  # pragma: no cover
     return config
 
 
+def get_script_directory() -> ScriptDirectory:
+    """Read the migration graph shipped with this package."""
+    config = Config()
+    config.set_main_option("script_location", str(Path(__file__).parent))
+    return ScriptDirectory.from_config(config)
+
+
+def schema_version(revision: str, script: ScriptDirectory | None = None) -> int:
+    """Return the schema version a revision produces: how many revisions it applies.
+
+    The count is taken from the graph, so the unnumbered revisions get a number too
+    (z9a0b1c2d3e4 is 39). For sequential revisions it equals int(revision): "0040" is 40.
+    """
+    script = script or get_script_directory()
+
+    # Trigger: Alembic resolves unique prefixes ("z9a" finds z9a0b1c2d3e4).
+    # Why: a version must name exactly one revision; a prefix that happens to resolve
+    # today becomes ambiguous when a later revision shares it.
+    # Outcome: only a full, known revision ID gets a version.
+    if revision not in {known.revision for known in script.walk_revisions()}:
+        raise ValueError(f"unknown alembic revision: {revision!r}")
+
+    return sum(1 for _ in script.walk_revisions("base", revision))
+
+
+def next_revision_id(script: ScriptDirectory) -> str:
+    """Return the ID for a new revision on top of the single current head."""
+    heads = script.get_heads()
+    if len(heads) != 1:
+        raise ValueError(
+            f"alembic has {len(heads)} heads {sorted(heads)}; if two branches added the "
+            "same numbered revision, renumber yours to the next ID and point its "
+            "down_revision at the new head (no merge revisions)"
+        )
+    return f"{schema_version(heads[0], script) + 1:0{REVISION_ID_DIGITS}d}"
+
+
+def assign_sequential_revision_ids(
+    context: MigrationContext,
+    revision: object,
+    directives: list[MigrationScript],
+) -> None:
+    """env.py `process_revision_directives` hook: name each new revision by its version."""
+    # Trigger: Alembic always hands the hook a context built from the script directory.
+    # Why: without the graph there is no head to count from; guessing an ID would
+    # silently fork the history.
+    # Outcome: fail fast instead of writing a revision with an unchecked ID.
+    if context.script is None:
+        raise RuntimeError("alembic revision context has no script directory")
+
+    rev_id = next_revision_id(context.script)
+    (head,) = context.script.get_heads()
+
+    for directive in directives:
+        # Trigger: `alembic revision --head <older rev> --splice` (or --head base).
+        # Why: the next ID only means "one past the head" if the revision revises that
+        # head; built on anything else it forks the graph into two heads.
+        # Outcome: refuse before Alembic writes the file.
+        # The CLI leaves `head` as None when --head is omitted; ScriptDirectory.generate_revision
+        # reads None as "head", so resolve it the same way.
+        requested = directive.head or "head"
+        built_on = [rev.revision for rev in context.script.get_revisions(requested) if rev]
+        if built_on != [head]:
+            raise ValueError(
+                f"new revision builds on {built_on or 'base'}, not the current head {head!r}; "
+                "build on the head (omit --head, or pass --head head)"
+            )
+        directive.rev_id = rev_id
+
+
 def reset_database():  # pragma: no cover
     """Drop and recreate all tables."""
     logger.info("Resetting database...")

basic_memory/alembic/versions/0040_vector_chunk_location_columns.py

@@ -0,0 +1,114 @@
+"""Key vector chunks by content and store their search row location in columns.
+
+A chunk key used to embed the search_index row id it was cut from
+("observation:95276:0"). Updating a note deletes and recreates its observations and
+relations, and Postgres never reuses ids, so every rewrite gave every observation and
+relation chunk a new key. Nothing matched the previous manifest and the whole note was
+re-embedded on each edit: about 86 chunks per edit for an agent maintaining large ledger
+notes (basic-memory-cloud tenant 0fffb994, 2026-10-08).
+
+The row id and chunk position move into ``source_type``, ``source_row_id`` and
+``chunk_index``, and the key becomes ``<type>:<sha256 of the chunk text>:<occurrence>``.
+Built-in pgvector embeddings are stored by chunk row id, so re-keying in place keeps
+every existing embedding: nothing is re-embedded by this migration.
+
+Revision ID: 0040
+Revises: z9a0b1c2d3e4
+Create Date: 2026-10-08 19:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+revision: str = "0040"
+down_revision: Union[str, None] = "z9a0b1c2d3e4"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Split chunk location into columns and re-key Postgres chunks by content.
+
+    SQLite chunk tables are created at runtime by the search repository, which
+    applies the same upgrade (``SQLITE_CHUNK_LOCATION_UPGRADE``) when it finds them.
+    """
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        ADD COLUMN IF NOT EXISTS source_type TEXT,
+        ADD COLUMN IF NOT EXISTS source_row_id INTEGER,
+        ADD COLUMN IF NOT EXISTS chunk_index INTEGER
+        """
+    )
+    op.execute(
+        """
+        UPDATE search_vector_chunks SET
+            source_type = split_part(chunk_key, ':', 1),
+            source_row_id = split_part(chunk_key, ':', 2)::integer,
+            chunk_index = split_part(chunk_key, ':', 3)::integer
+        WHERE source_type IS NULL
+        """
+    )
+    # Old keys ("type:id:n") and new keys ("type:<64 hex>:n") cannot collide, so the
+    # unique (project_id, entity_id, chunk_key) constraint holds throughout.
+    op.execute(
+        """
+        UPDATE search_vector_chunks AS chunks
+        SET chunk_key = ranked.source_type || ':' || ranked.source_hash || ':'
+            || ranked.occurrence
+        FROM (
+            SELECT id, source_type, source_hash,
+                ROW_NUMBER() OVER (
+                    PARTITION BY project_id, entity_id, source_type, source_hash
+                    ORDER BY source_row_id, chunk_index, id
+                ) - 1 AS occurrence
+            FROM search_vector_chunks
+        ) AS ranked
+        WHERE ranked.id = chunks.id
+        """
+    )
+    # pgvector finds embeddings by chunk row id, so re-keying keeps them. An external
+    # index (Milvus) stores the old key itself; re-embed those chunks.
+    op.execute(
+        """
+        UPDATE search_vector_chunks SET embedding_status = 'pending'
+        WHERE vector_index NOT IN ('', 'sqlite-vec', 'pgvector')
+        """
+    )
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        ALTER COLUMN source_type SET NOT NULL,
+        ALTER COLUMN source_row_id SET NOT NULL,
+        ALTER COLUMN chunk_index SET NOT NULL
+        """
+    )
+
+
+def downgrade() -> None:
+    """Restore row-id chunk keys and drop the location columns."""
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute(
+        """
+        UPDATE search_vector_chunks
+        SET chunk_key = source_type || ':' || source_row_id || ':' || chunk_index
+        """
+    )
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        DROP COLUMN IF EXISTS chunk_index,
+        DROP COLUMN IF EXISTS source_row_id,
+        DROP COLUMN IF EXISTS source_type
+        """
+    )

basic_memory/alembic/versions/0041_index_vector_chunk_location.py

@@ -0,0 +1,48 @@
+"""Index vector chunks by the search row they were cut from.
+
+A filtered vector search hands the index the filter as SQL over the chunk manifest and
+admits chunks by their search row: ``(project_id, source_type, source_row_id)`` (#1746).
+Without an index on those columns, every filtered search read the whole chunk table
+(373,000 rows in the largest production project) to find the admitted chunks.
+
+SQLite creates its chunk table and indexes at runtime in the search repository, which
+creates this index too.
+
+Revision ID: 0041
+Revises: 0040
+Create Date: 2026-10-11 15:30:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+revision: str = "0041"
+down_revision: Union[str, None] = "0040"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create the chunk location index on Postgres."""
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_search_vector_chunks_location
+        ON search_vector_chunks (project_id, source_type, source_row_id)
+        """
+    )
+
+
+def downgrade() -> None:
+    """Drop the chunk location index on Postgres."""
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute("DROP INDEX IF EXISTS idx_search_vector_chunks_location")

basic_memory/alembic/versions/0042_nfc_file_paths.py

@@ -0,0 +1,291 @@
+"""Normalize stored file paths to Unicode NFC and merge NFC/NFD twin entities.
+
+macOS filesystems resolve the NFC and NFD spellings of a name to one file but
+report whichever form is on disk, and file-sync tools rewrite that form
+(Syncthing keeps NFD names on macOS). Before #1275 the index keyed entities by
+the raw path, so a vault could hold two rows for one file -- the second with a
+`-1` permalink -- and notes whose stored key was NFD. Paths now enter the index
+in NFC on macOS (`basic_memory.utils.nfc_path`); this migration brings existing
+rows to the same form so the first index pass after upgrading does not see a
+wave of moves.
+
+For each group of entities whose paths are equal after NFC normalization, the
+oldest row (lowest id, which holds the original permalink) is kept:
+
+- an accepted write that has not reached disk yet (`note_content` not `synced`)
+  moves to the kept row; two such writes for one file stop the upgrade instead
+  of dropping one;
+- references to a twin (`relation.to_id`, `note_file_vacate.entity_id`,
+  `accepted_project_note_change.entity_id`) move to the kept row; a relation
+  that would duplicate one the kept row already receives is dropped instead;
+- rows that only describe the twin are deleted, and the kept row's checksums
+  are cleared so the next index pass re-reads the file, the source of truth.
+
+`note_file_vacate` keys markers by path, so NFC/NFD spellings of one vacated
+path are merged to the marker whose checksum guard matches the file on disk. Embeddings of
+deleted vector chunks are left to the semantic index's orphan sweep, because
+removing them here would need the sqlite-vec extension inside the migration.
+
+Linux and Windows filesystems keep NFC and NFD names as two distinct files, so
+there stored paths stay byte-exact and this migration does nothing -- the same
+rule `nfc_path` applies.
+
+Revision ID: 0042
+Revises: 0041
+Create Date: 2026-10-14 12:00:00.000000
+
+"""
+
+import hashlib
+import sys
+import unicodedata
+from collections import defaultdict
+from pathlib import Path
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0042"
+down_revision: Union[str, None] = "0041"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# (table, columns the statement needs, statement), run in order for each twin.
+# A statement runs only when its table and columns exist: search_index is derived
+# state whose shape differs across older databases, and the next index pass
+# rebuilds it anyway.
+TWIN_STATEMENTS = (
+    # The twin's outgoing edges describe the same file the kept row describes.
+    ("relation", ("from_id",), "DELETE FROM relation WHERE from_id = :twin"),
+    # An edge into the twin that duplicates an edge into the kept row would break
+    # uix_relation_from_id_to_id once redirected; the kept row's edge stays.
+    (
+        "relation",
+        ("from_id", "to_id", "relation_type"),
+        "DELETE FROM relation WHERE to_id = :twin AND EXISTS ("
+        "SELECT 1 FROM relation AS kept WHERE kept.from_id = relation.from_id "
+        "AND kept.to_id = :keeper AND kept.relation_type = relation.relation_type)",
+    ),
+    ("relation", ("to_id",), "UPDATE relation SET to_id = :keeper WHERE to_id = :twin"),
+    (
+        "note_file_vacate",
+        ("entity_id",),
+        "UPDATE note_file_vacate SET entity_id = :keeper WHERE entity_id = :twin",
+    ),
+    (
+        "accepted_project_note_change",
+        ("entity_id",),
+        "UPDATE accepted_project_note_change SET entity_id = :keeper WHERE entity_id = :twin",
+    ),
+    ("observation", ("entity_id",), "DELETE FROM observation WHERE entity_id = :twin"),
+    ("note_section", ("entity_id",), "DELETE FROM note_section WHERE entity_id = :twin"),
+    (
+        "memory_time_index",
+        ("entity_id",),
+        "DELETE FROM memory_time_index WHERE entity_id = :twin",
+    ),
+    (
+        "relation_search_refresh",
+        ("entity_id",),
+        "DELETE FROM relation_search_refresh WHERE entity_id = :twin",
+    ),
+    ("note_content", ("entity_id",), "DELETE FROM note_content WHERE entity_id = :twin"),
+    ("search_index", ("entity_id",), "DELETE FROM search_index WHERE entity_id = :twin"),
+    (
+        "search_vector_chunks",
+        ("entity_id",),
+        "DELETE FROM search_vector_chunks WHERE entity_id = :twin",
+    ),
+)
+
+# (table, key column, path columns) for every stored project-relative path.
+PATH_COLUMNS = (
+    ("entity", "id", ("file_path",)),
+    ("note_content", "entity_id", ("file_path",)),
+    ("note_file_vacate", "id", ("file_path",)),
+    ("accepted_project_note_change", "id", ("file_path", "previous_file_path")),
+    # search_index has no single-column key on every backend; the entity id plus
+    # the stored path identifies the rows, so the old path is matched as well.
+    ("search_index", "entity_id", ("file_path",)),
+)
+
+
+def _nfc(path: str) -> str:
+    return unicodedata.normalize("NFC", path)
+
+
+def _nfc_or_none(path: str | None) -> str | None:
+    return None if path is None else _nfc(path)
+
+
+def _table_columns(connection: sa.Connection) -> dict[str, set[str]]:
+    inspector = sa.inspect(connection)
+    # Reflect only tables this migration uses. Inspecting unrelated vec0 tables
+    # requires sqlite-vec on the migration connection even without reading rows.
+    needed_tables = {table for table, _, _ in TWIN_STATEMENTS} | {
+        table for table, _, _ in PATH_COLUMNS
+    }
+    return {
+        table: {column["name"] for column in inspector.get_columns(table)}
+        for table in inspector.get_table_names()
+        if table in needed_tables
+    }
+
+
+def _has(columns: dict[str, set[str]], table: str, *names: str) -> bool:
+    return table in columns and set(names) <= columns[table]
+
+
+def _keep_unwritten_note_content(
+    connection: sa.Connection, columns: dict[str, set[str]], keeper: int, twins: list[int]
+) -> None:
+    """Move an accepted write that has not reached disk yet onto the kept entity.
+
+    A `synced` row equals the file on disk, so dropping it loses nothing. Any other
+    status is accepted content that exists only in the database. `updated_at` is
+    no guide: reconciliation refreshes it on rows whose bytes did not change.
+    """
+    if not _has(columns, "note_content", "entity_id", "file_write_status"):
+        return
+    rows = connection.execute(
+        sa.text(
+            "SELECT entity_id, file_write_status FROM note_content WHERE entity_id IN :ids"
+        ).bindparams(sa.bindparam("ids", expanding=True)),
+        {"ids": [keeper, *twins]},
+    ).all()
+    unwritten = [entity_id for entity_id, status in rows if status != "synced"]
+    if len(unwritten) > 1:
+        raise RuntimeError(
+            "Entities "
+            + ", ".join(str(entity_id) for entity_id in sorted(unwritten))
+            + " are NFC/NFD spellings of one file and each holds an accepted write that "
+            "has not been written to disk. Let the previous Basic Memory version finish "
+            "writing them (or resolve the note by hand), then upgrade again."
+        )
+    owners = {entity_id for entity_id, _ in rows}
+    source = unwritten[0] if unwritten else (keeper if keeper in owners else None)
+    if source is None and owners:
+        source = min(owners)
+    if source is None or source == keeper:
+        return
+    connection.execute(
+        sa.text("DELETE FROM note_content WHERE entity_id = :keeper"), {"keeper": keeper}
+    )
+    # external_id mirrors the owning entity and reads look note content up by it,
+    # so the adopted row takes the keeper's external_id along with its entity_id.
+    connection.execute(
+        sa.text(
+            "UPDATE note_content SET entity_id = :keeper, "
+            "external_id = (SELECT external_id FROM entity WHERE id = :keeper) "
+            "WHERE entity_id = :owner"
+        ),
+        {"keeper": keeper, "owner": source},
+    )
+
+
+def _merge_twins(connection: sa.Connection, columns: dict[str, set[str]]) -> None:
+    rows = connection.execute(
+        sa.text("SELECT id, project_id, file_path FROM entity ORDER BY id")
+    ).all()
+    groups: dict[tuple[int, str], list[int]] = defaultdict(list)
+    for entity_id, project_id, file_path in rows:
+        groups[(project_id, _nfc(file_path))].append(entity_id)
+
+    for ids in groups.values():
+        if len(ids) < 2:
+            continue
+        keeper, twins = ids[0], ids[1:]
+        _keep_unwritten_note_content(connection, columns, keeper, twins)
+        for twin in twins:
+            params = {"keeper": keeper, "twin": twin}
+            for table, needed, statement in TWIN_STATEMENTS:
+                if _has(columns, table, *needed):
+                    connection.execute(sa.text(statement), params)
+            connection.execute(sa.text("DELETE FROM entity WHERE id = :twin"), params)
+        connection.execute(
+            sa.text("UPDATE entity SET checksum = NULL, sync_checksum = NULL WHERE id = :keeper"),
+            {"keeper": keeper},
+        )
+
+
+def _file_checksum(project_root: str | None, file_path: str) -> str | None:
+    """SHA-256 of the file on disk, the same digest the indexer stores as a guard."""
+    if not project_root:
+        return None
+    try:
+        return hashlib.sha256((Path(project_root) / file_path).read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
+def _merge_vacate_markers(connection: sa.Connection, columns: dict[str, set[str]]) -> None:
+    """Keep one marker per vacated path, since markers are unique by path.
+
+    The marker whose checksum guard matches the file on disk is the current one;
+    ids and timestamps are no guide because a refreshed marker keeps its id. When
+    no guard matches (or the file is gone) every marker is already stale, and the
+    lowest id is kept, which leaves the state the database held before.
+    """
+    if not _has(columns, "note_file_vacate", "id", "project_id", "file_path", "file_checksum"):
+        return
+    project_roots = {
+        project_id: path
+        for project_id, path in connection.execute(sa.text("SELECT id, path FROM project")).all()
+    }
+    groups: dict[tuple[int, str], list[tuple[int, str | None]]] = defaultdict(list)
+    for marker_id, project_id, file_path, checksum in connection.execute(
+        sa.text("SELECT id, project_id, file_path, file_checksum FROM note_file_vacate ORDER BY id")
+    ).all():
+        groups[(project_id, _nfc(file_path))].append((marker_id, checksum))
+    for (project_id, file_path), markers in groups.items():
+        if len(markers) < 2:
+            continue
+        on_disk = _file_checksum(project_roots.get(project_id), file_path)
+        current = next((marker for marker in markers if marker[1] == on_disk), markers[0])
+        for marker_id, _ in markers:
+            if marker_id != current[0]:
+                connection.execute(
+                    sa.text("DELETE FROM note_file_vacate WHERE id = :id"), {"id": marker_id}
+                )
+
+
+def _normalize_paths(connection: sa.Connection, columns: dict[str, set[str]]) -> None:
+    for table, key, path_columns in PATH_COLUMNS:
+        if not _has(columns, table, key, *path_columns):
+            continue
+        selected = ", ".join(path_columns)
+        rows = connection.execute(sa.text(f"SELECT DISTINCT {key}, {selected} FROM {table}")).all()
+        for row in rows:
+            row_key, values = row[0], tuple(row[1:])
+            normalized = tuple(_nfc_or_none(value) for value in values)
+            if normalized == values:
+                continue
+            assignments = ", ".join(f"{column} = :new_{column}" for column in path_columns)
+            matches = " AND ".join(
+                f"{column} IS NULL" if value is None else f"{column} = :old_{column}"
+                for column, value in zip(path_columns, values)
+            )
+            connection.execute(
+                sa.text(f"UPDATE {table} SET {assignments} WHERE {key} = :key AND {matches}"),
+                {
+                    "key": row_key,
+                    **{f"new_{column}": value for column, value in zip(path_columns, normalized)},
+                    **{f"old_{column}": value for column, value in zip(path_columns, values)},
+                },
+            )
+
+
+def upgrade() -> None:
+    """Merge NFC/NFD twin entities and store every path in NFC (macOS only)."""
+    if sys.platform != "darwin":
+        return
+    connection = op.get_bind()
+    columns = _table_columns(connection)
+    _merge_twins(connection, columns)
+    _merge_vacate_markers(connection, columns)
+    _normalize_paths(connection, columns)
+
+
+def downgrade() -> None:
+    """Keep the NFC paths; the older schema reads them as ordinary paths."""

basic_memory/alembic/versions/bcdbd5a942ca_relation_to_id_set_null_on_delete.py

@@ -0,0 +1,77 @@
+"""relation.to_id foreign key becomes ON DELETE SET NULL
+
+Deleting an entity used to take every inbound relation row with it. The wikilink
+stayed in the source note's markdown, but the graph forgot the edge existed, so a
+"find broken links" report came back clean over a vault full of them.
+
+to_id has always been nullable, and the indexer already produces exactly the state
+we want here -- to_id NULL with to_name holding the source's link text -- for a link
+pointing at a note that does not exist yet. A deleted target should land in that same
+unresolved state instead of vanishing, and forward-reference resolution then re-links
+the row for free if the target is ever recreated.
+
+from_id keeps CASCADE. An entity really does own the relations it declares.
+
+Revision ID: bcdbd5a942ca
+Revises: 7f6a2b8c9d10
+Create Date: 2026-08-28 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "bcdbd5a942ca"
+down_revision: Union[str, None] = "7f6a2b8c9d10"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+# The initial schema created relation's entity foreign keys without names, and SQLite
+# has no way to reference an anonymous constraint. Handing batch_alter_table a naming
+# convention lets it address the reflected FK by the name the convention would have
+# given it. Side effect worth knowing about: the table recreate writes those names into
+# the schema, so from_id's FK comes out named too. Cosmetic, and an improvement.
+RELATION_NAMING_CONVENTION = {"fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s"}
+SQLITE_TO_ID_FK = "fk_relation_to_id_entity"
+
+# Postgres named it for us when the initial schema left it anonymous.
+POSTGRES_TO_ID_FK = "relation_to_id_fkey"
+
+
+def _set_to_id_ondelete(ondelete: str) -> None:
+    """Point relation.to_id's foreign key at a different ON DELETE action."""
+    dialect = op.get_bind().dialect.name
+
+    if dialect == "sqlite":
+        # SQLite cannot alter a foreign key in place; batch mode does the copy-and-swap.
+        # Same shape as a1b2c3d4e5f6.
+        with op.batch_alter_table(
+            "relation", schema=None, naming_convention=RELATION_NAMING_CONVENTION
+        ) as batch_op:
+            batch_op.drop_constraint(SQLITE_TO_ID_FK, type_="foreignkey")
+            batch_op.create_foreign_key(
+                SQLITE_TO_ID_FK, "entity", ["to_id"], ["id"], ondelete=ondelete
+            )
+    else:
+        op.drop_constraint(POSTGRES_TO_ID_FK, "relation", type_="foreignkey")
+        op.create_foreign_key(
+            POSTGRES_TO_ID_FK, "relation", "entity", ["to_id"], ["id"], ondelete=ondelete
+        )
+
+
+def upgrade() -> None:
+    """Stop erasing an entity's inbound relations along with the entity."""
+    _set_to_id_ondelete("SET NULL")
+
+
+def downgrade() -> None:
+    """Go back to erasing inbound relations on delete.
+
+    Rows already unresolved (to_id NULL) stay that way. This restores the constraint;
+    it cannot un-forget what CASCADE already ate.
+    """
+    _set_to_id_ondelete("CASCADE")