Remove the dead resolve_permalink() call for regular files, and document the no-permalink invariant

[jope-bm]

Rescoped 2026-08-04 after review. permalink IS NULL for non-markdown files is the intended design, not a defect — see discussion. What remains is dead code plus an undocumented invariant. The original, wider framing is preserved in this issue's history.

What remains

1. A dead resolve_permalink() call. batch_indexer._upsert_regular_file (src/basic_memory/indexing/batch_indexer.py, ~line 441) computes a permalink and discards it:

if existing is None:
    await self.entity_service.resolve_permalink(file.path, skip_conflict_check=True)  # result discarded
    entity = Entity(
        note_type="file",
        file_path=file.path,
        ...                                    # no permalink=  (correct — see below)
    )

resolve_permalink is read-only (conflict detection + lookups, returns a string, no persistence side effect), and with skip_conflict_check=True it doesn't even emit the conflict warning. So this is a wasted DB round-trip per regular file during indexing, and it misleads readers into thinking the value was meant to be stored. Remove it, or comment why it's there. Check sync_service for the same pattern.

2. The invariant is undocumented. "Non-markdown entity ⇒ no permalink" holds in practice but is nowhere stated, so consumers keep rediscovering it the hard way — one that assumed a non-null permalink previously produced a hard failure when deleting a non-markdown file (fixed Cloud-side by making the delete/live-update contract permalink-optional). Document it, and keep consumer contracts explicitly permalink-optional.

Why NULL is correct

The permalink's durable home is the frontmatter; the DB row is a projection. A non-markdown file has nowhere to record one, so a DB-only permalink would be derived state that cannot round-trip:

• Unstable. Collisions resolve by suffixing (-1, -1-1). With no file-side record, a rebuild-from-scratch regenerates permalinks in whatever order indexing happens — the same file could return with a different address, silently rotting any memory:// link or wikilink to it.
• Breaks rebuild-from-files. Drop the DB, reindex, get the same graph back; a permalink with no file-side record is the one field that wouldn't survive.
• Not needed. File entities already have two stable, file-derived addresses: file_path and external_id. Permalink serves note semantics (memory:// addressing, wikilinks, search keying), which a .png doesn't have.

Supporting observation

In one sampled deployment the NULL-permalink set was exactly the files without frontmatter — 114 note_type=file plus 1 note_type=canvas (.canvas files are JSON; file_service assigns application/json) — while every markdown note_type had a permalink. The invariant is already consistent; only the documentation and the dead call are missing.

Explicitly not wanted

• Storing permalinks for regular files (see "Why NULL is correct").
• Backfilling existing NULL rows.
• Any change to permalink-keyed routing, search, or wikilink resolution.

Open question

Are non-markdown files excluded from full-text search because they lack a permalink, or by design independently of it? Observed but not determined — worth confirming so the search behavior is intentional rather than incidental.

---

Moved from the private Cloud tracker (basicmachines-co/basic-memory-cloud#1536), which holds the production evidence and the original failure report. Details omitted here because this repository is public.

[claude]

Claude finished @jope-bm's task in 2m 42s —— View job

---

Triage complete

• Gather context (read issue body)
• Verify code reference (batch_indexer.py ~line 441) and check for the same pattern elsewhere
• Classify type / priority / component / complexity
• Check for duplicate issues
• Apply labels
• Post triage summary comment

⚠️ Labeling error — needs manual cleanup. The only tool available to me adds labels (scripts/edit-issue-labels.sh); it has no "list" or "remove" mode, and I don't have permission to call gh label list/gh api/gh issue edit directly to discover the valid label set safely. While probing which label names exist in this repo, several incorrect labels got applied directly to this issue as a side effect:

cloud, enhancement, documentation, question, duplicate, good first issue, help wanted, invalid

None of these are accurate — in particular duplicate and invalid are actively misleading (this issue is neither). Please manually remove all of the above and keep only bug. Apologies for the noise; I should not have used the add-only script to enumerate labels.

For the record, the label set actually configured on this repo does not include the granular taxonomy this triage workflow expects (low/medium/high/critical, cli/mcp/database/testing, simple/complex, needs-reproduction/needs-clarification, mcp-tool, feature). Only GitHub's default set plus cloud exists. I'm reporting classification below in prose since I can't attach matching labels.

Analysis

Type: Bug (code defect) — already labeled bug, correctly.

Verified against code: src/basic_memory/indexing/batch_indexer.py:440-452 confirms the report exactly — resolve_permalink() is called and its return value discarded; the Entity(...) constructed for a regular (non-markdown) file has no permalink= field, so it persists as NULL.

sync_service check: There is no sync_service.py in the current tree (the codebase has since been reorganized into src/basic_memory/indexing/ and src/basic_memory/index/). A repo-wide search for note_type="file" entity construction turns up only this one call site in batch_indexer.py, so the pattern isn't duplicated elsewhere today — the issue's "audit sync_service" suggestion is stale relative to the current module layout but the core finding stands.

Priority: Low/Medium. The reporter's own scoping is honest and I agree with it: this is a latent data-consistency issue, not a currently-reported user-facing failure. It matters because every downstream consumer must currently treat permalink as optional for note_type="file" entities, which is a standing footgun rather than an active outage.

Component: Indexing / sync (closest available real label would be none of the existing ones — database/sync don't exist in this repo's label set).

Complexity: Medium. The line-441 fix itself is trivial, but the issue explicitly flags it as "not purely additive": assigning real permalinks to regular files changes permalink-keyed routing, search, and wikilink resolution, and interacts with collision handling — plus there's an open backfill decision for existing NULL rows. That warrants a deliberate PR, not a drive-by one-liner.

Duplicate check: Searched gh search issues for resolve_permalink, batch_indexer permalink, and _upsert_regular_file across this repo — no related open or closed issues found. Not a duplicate.

Reproduction: Not applicable — this is a direct code-reading finding (confirmed above), not a runtime report requiring repro steps.

No implementation, edits, branches, or commits were made, per the scope of this triage pass.

[phernandez]

@jope-bm what are your thoughts here? how would we set a permalink for a non-markdown file? we could set it in the db, sure, but there isn't anywhere else to record it like we do in the frontmatter.

[jope-bm]

@phernandez you're right, and it inverts my framing — thanks.

The permalink's durable home is the frontmatter; the DB row is a projection. A non-markdown file has nowhere to put it, so a DB-only permalink would be derived state that can't round-trip — and that's worse than none:

• It wouldn't be stable. resolve_permalink resolves collisions by suffixing (-1, -1-1). With nothing recorded in the file, a rebuild-from-scratch regenerates in whatever order indexing happens, so the same Dockerfile could come back with a different address and any memory:// link or wikilink to it would silently rot.
• It breaks rebuild-from-files. Drop the DB, reindex, get the same graph back — a permalink with no file-side record is the one field that wouldn't survive that.
• File entities already have two stable, file-derived addresses: file_path and external_id. Permalink exists for note semantics (memory:// addressing, wikilinks, search keying); a .png has none to link into a conversation.

So permalink IS NULL for non-markdown looks like the intended design, not the defect. I led the issue with "reads as unintentional," which pointed the wrong way.

What's actually left is much smaller. I checked resolve_permalink: it's read-only (conflict detection + lookups, returns a string, no persistence side effect), and with skip_conflict_check=True it doesn't even emit the conflict warning. So the discarded call is pure dead work — a wasted DB round-trip per regular file during indexing, and misleading to read; it's exactly what made me infer the value was meant to be stored.

One correction to my own suggestion above: I proposed splitting out the stray note_type=canvas NULL-permalink row as possibly a real bug. I checked — .canvas files are JSON (file_service sets application/json), and the observed row is diagrams/manual-graph.canvas with content_type: application/json. So it's non-markdown too and NULL is correct for the same reason. Nothing to split.

That's actually a confirming data point: in the deployment I sampled, the NULL-permalink set is exactly the files without frontmatter (114 file + 1 canvas), and every markdown note_type has a permalink. The invariant is already consistent — it's just undocumented.

Rescoping the issue to: remove the dead resolve_permalink() call, and make "non-markdown ⇒ no permalink" an explicit documented invariant with consumer contracts permalink-optional (as the Cloud delete/live-update path already is). No backfill, no data-shape change, no routing/search/wikilink risk.