Start with status, then repair deliberately.

Is Link Ready?

lnk health
lnk status --validate
lnk doctor
lnk next

If link is not on your PATH, run from the source checkout with python3 link.py, or add ~/.local/bin to your shell path.

MCP Is Not Visible

lnk verify-mcp
python3 -m pip index versions link-mcp

Restart the MCP client after changing its config. If your installer printed a venv Python path, use that exact path in the MCP config.

You do not need lnk serve or serve.py running for MCP. The web viewer is separate from the MCP server.

Ingest Is Blocked

lnk ingest-status

Blocked ingest usually means a raw source has secret-looking values, cannot be read safely, or source representation counts may be incomplete. Redact or fix the local file, then ask the agent to ingest again.

Interrupted Writes

lnk operations
lnk operations ~/link --recover remember-2026-06-30.json --confirm
lnk validate
lnk doctor --fix

If a memory write was interrupted, Link leaves a marker under wiki/.link-operations/. Inspect it before deleting anything manually. When the marker includes a rollback snapshot, lnk operations --recover <marker> previews the restore plan and --confirm applies it. Then validate the wiki and repair generated indexes if needed.

Graph Is Stale

lnk rebuild-index
lnk rebuild-backlinks
lnk validate

Run this after manual Obsidian edits, hand-written wikilinks, or a failed ingest.

Demo Looks Stale

link-demo/ is generated local output and is ignored by git. If it was created with an older Link version, regenerate it:

python3 link.py demo link-demo --force
python3 link.py health link-demo
python3 link.py query "why does Link help agents?" link-demo --budget small

The current generated demo should include three raw sources, source-backed wiki pages, four starter memories (three reviewed, one pending review), one exploration, current backlinks, and schema v1.

Session Hooks Are Not Firing

Check the agent's settings file (for Claude Code, ~/.claude/settings.json) for the Link entries under SessionStart/SessionEnd; rerunning lnk connect <agent> --hooks --write is idempotent and repairs a workspace runtime that predates hooks. If sessions start with the brief but nothing is captured at session end, that is usually correct behavior — trivial sessions, duplicates, and restatements of existing memory are skipped by design. See exactly why with:

lnk hook session-end ~/link --explain

Semantic Recall Is Not Working

lnk semantic ~/link shows the active provider and tier. Common causes: the extra was installed into a different Python than the one running Link (the status output names the interpreter it checked, and the error prints the exact venv-side command such as python3 -m link_mcp --semantic-setup); the one-time model fetch has not run (lnk semantic ~/link --setup); or LINK_SEMANTIC=off is set. Recall itself never downloads anything — a missing model degrades silently to lexical recall by design.

The Wiki Feels Slow

lnk benchmark "agent memory"
lnk graph-summary "agent memory" --limit 40 --depth 1

Large graph views intentionally open bounded first. Use type filters, node search, depth controls, and explicit all-data loading only when you need search or filtering across every page.

If lnk health or lnk benchmark shows low persistent-cache reuse after repeated runs, inspect recently edited pages or generated files that are changing on every request.

From a source checkout, use the synthetic smoke script when you want local scale evidence without touching your real wiki:

python3 scripts/smoke_large_wiki.py --pages 10000

pip Is Blocked By Homebrew Python

If pip reports externally-managed-environment, avoid forcing packages into Homebrew Python. Use a dedicated venv:

python3 -m venv ~/.link-mcp-venv
~/.link-mcp-venv/bin/python -m pip install --upgrade pip link-mcp

The current installers do this automatically when needed.