Regular (non-.md) files are indexed with a NULL permalink

[jope-bm]

Summary

batch_indexer._upsert_regular_file computes a permalink for a regular (non-markdown) file and then discards it, creating the entity without one. Every non-.md file — Dockerfile, scripts/*.py, images — is therefore indexed with permalink = NULL.

src/basic_memory/indexing/batch_indexer.py (~line 441):

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,
        checksum=checksum,
        title=Path(file.path).name,
        ...                                    # no permalink=
    )

The resolve_permalink() call reads as unintentional rather than deliberate: the value is computed and thrown away. sync_service should be checked for the same pattern.

Why it matters

A permalink is an entity's stable address, used by memory:// references, wikilinks, and permalink-keyed lookups. Because these rows have none, every consumer must treat permalink as optional — and a consumer that didn't previously produced a hard failure when deleting a non-markdown file (tracked privately; that specific delete path has since been fixed by making the delete/live-update contract permalink-optional).

Honest scoping: this is a latent-consistency issue, not a live user-facing bug. Nothing is known to be broken today; the value of fixing it is removing a class of "assumed permalink exists" defects at the source instead of guarding each consumer.

Suggested fix

1. Assign the resolved permalink when indexing a regular file (stop discarding it). Audit sync_service for the same pattern.
2. Decide the backfill question for existing NULL rows — new rows having permalinks while old ones don't is its own inconsistency. (Observed in one deployment: ~114 note_type=file rows, all NULL, alongside a stray note_type=canvas row, so the assumption is not strictly limited to note_type=file.)
3. Regression test: index a non-.md file → assert a permalink is stored → delete it → assert deleted and not resurrected.

Not purely additive. Giving regular files real permalinks changes data shape (permalink-keyed routing, search, wikilink resolution) and interacts with permalink-collision handling, so it warrants a deliberate decision rather than a drive-by change.

Open questions

• Are non-markdown files excluded from full-text search because they lack a permalink, or by design independently of it? Observed but not determined.
• Should regular files get a permalink at all, or is NULL the intended design and the resolve_permalink() call simply dead code to remove? Either resolution is coherent; the current state — computing a value and discarding it — is not.

---

Moved from the private Cloud tracker (basicmachines-co/basic-memory-cloud#1536), which holds the production evidence, the original failure report, and the verification that the delete path is fixed. 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.