Contributing

Keep Link local, inspectable, and reliable.

Contributions should make agent memory easier to trust: clearer onboarding, safer writes, faster retrieval, better validation, and tighter docs.

Branches

Contributions should come through pull requests. Please target main unless the maintainer asks for a different branch. The develop branch is a maintainer integration branch for staging larger release work before it is proposed to main.

Before Opening A PR

python3 -m pip install "ruff>=0.8,<1"
python3 -m pip install "pytest>=8,<10"
python3 -m ruff check .
python3 -m pytest tests
python3 -m py_compile link.py serve.py scripts/check_release_hygiene.py scripts/check_runtime_duplication.py scripts/check_tool_contract.py scripts/prepare_release.py scripts/smoke_first_use.py scripts/smoke_http_viewer.py scripts/smoke_large_wiki.py scripts/smoke_mcp_stdio.py mcp_package/link_core/*.py mcp_package/link_mcp/server.py mcp_package/link_mcp/__main__.py mcp_package/link_mcp/__init__.py
python3 scripts/smoke_first_use.py
python3 scripts/smoke_http_viewer.py
python3 scripts/smoke_large_wiki.py --pages 1000
python3 scripts/check_release_hygiene.py
python3 scripts/check_runtime_duplication.py
python3 scripts/check_tool_contract.py
bash -n integrations/*/install.sh integrations/*/uninstall.sh integrations/_shared/*.sh
pwsh -NoProfile -Command "Get-ChildItem integrations -Recurse -Include *.ps1 | ForEach-Object { [scriptblock]::Create((Get-Content -Raw $_.FullName)) | Out-Null }"
python3 link.py demo /tmp/link-mcp-smoke --force
PYTHONPATH=mcp_package python3 scripts/smoke_mcp_stdio.py /tmp/link-mcp-smoke/wiki
git diff --check

For graph or query performance changes, also run a local 10k-page stress check. It is intentionally not part of normal PR CI.

python3 scripts/smoke_large_wiki.py --pages 10000

PR Description

  • What changed.
  • How you tested it.
  • Whether it touches memory writes, installers, MCP behavior, HTTP endpoints, or automation.
  • Screenshots or GIFs for UI changes.

Do not include personal wiki data, raw sources, registry tokens, .env files, or local MCP credentials in a PR.

Project Structure

link/
|-- LINK.md              # schema and instructions for agents
|-- raw/                 # source documents, ignored by git
|-- .link-cache/         # local derived cache, ignored by git
|-- wiki/                # compiled knowledge, ignored by git except scaffolding
|-- docs/                # GitHub Pages product and docs site
|-- integrations/        # one-step setup per AI tool
|-- mcp_package/         # PyPI package for link-mcp and shared link_core
|-- scripts/             # release and hygiene tooling
|-- serve.py             # local web viewer and HTTP API
`-- link.py              # local utility CLI

Design Principles

  • Every claim links to a source.
  • Confidence tags make uncertainty visible.
  • log.md records wiki operations.
  • Pages mature from seed to established.
  • Agents should use query_link first, then follow up with graph/context tools only when the compact packet is insufficient.
  • The local web viewer has no runtime dependencies beyond Python stdlib.
  • The wiki is plain Markdown, so it works with git, Obsidian, and normal editors.

Installer Integrations

Agent installers are part of Link's first-use product surface. If a change touches Codex, Claude Code, Kiro, Cursor, Copilot, VS Code, Antigravity, MCP config writing, or PowerShell support, follow the maintainer checklist in integrations/README.md. The key rule is simple: installers should preserve existing user instructions, keep CLI/MCP independent from the web viewer, and update macOS/Linux plus Windows paths together.