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 ruff check .
python3 -m unittest discover -s 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
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

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.