Skip to content

expose the wiki link graph as kb.backlinks (roadmap 1.4) #732

Description

@joaovictor91123

What you're trying to do

ROADMAP.md's 1.4 milestone: "Backlinks: [[wikilinks]] are validated
today, then discarded; persist the link graph and render it." The "render"
half exists — wiki_render.backlinks() computes the inbound-link map
internally, used by render_moc to rank pages by how referenced they are.
But there's no agent-facing way to ask "what links here?" or "what does
this page link to?" — the graph is only visible baked into rendered
markdown output, never as structured data.

What you've tried

  • vouch render-wiki writes index.md + MOC.md, which embeds inbound
    counts and titles as markdown prose (- **[[Page]]** (N inbound)) — an
    agent would have to parse rendered markdown to recover the graph.
  • kb.neighbors looks adjacent but is entirely disjoint: it walks the
    claim/entity/relation graph (graph.find_neighbors), never [[wikilink]]
    edges between pages — grepped graph.py for any wikilink handling and
    found none.
  • Checked capabilities.METHODS and server.py/jsonl_server.py — no
    kb.backlinks, kb.wiki_graph, or equivalent exists.

Suggested shape

kb.backlinks(page_id: str | None = None), registered the same four ways
as every other kb.* method:

  • With page_id: that page's inbound and outbound [[wikilink]] titles
    — inbound already exists (wiki_render.backlinks), outbound would be a
    small new sibling function walking the same page's own body.
  • Without page_id: the full inbound map, i.e. wiki_render.backlinks()
    exposed directly.
  • Unknown page_id → the same "not found" contract kb.neighbors uses for
    an unknown root node.
  • CLI: vouch backlinks [page_id].

Archived pages should be excluded the same way render-wiki already
excludes them (#695) — a link into an archived page is exactly as dead as
a link into nothing, and that pattern shouldn't be reinvented per-caller.

Compatibility considerations

Purely additive, read-only — no VEP needed. wiki_render.py's own
docstring already frames these as "regenerable views... like the SQLite
index, not authored knowledge," so persisting the graph to disk (the
literal other half of "persist the link graph") would be a bigger,
riskier change (cache invalidation, when to rebuild, whether
kb.index_rebuild should also touch it) that cuts against that stated
design — exposing the existing computed-on-demand view as a real method is
the low-risk piece of this roadmap item; the on-disk persistence half can
stay open as a separate question if someone wants to make that case.

Alternatives

Folding this into kb.neighbors — rejected, the claim/entity/relation
graph and the page-to-page wikilink graph are structurally disjoint (no
overlap in edges, sources, or node kinds), and conflating them would make
kb.neighbors' contract harder to reason about for both.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions