link

<p align="center">
  <img src="logo.svg" alt="Link" width="128">
</p>

<h1 align="center">Link</h1>

<h2 align="center">Local memory for AI agents.</h2>

<p align="center">
  Link gives Codex, Claude, Cursor, Kiro, VS Code, Copilot, Antigravity, and
  other local agents the same source-backed memory, stored locally as Markdown.
</p>

<p align="center">
  <a href="https://gowtham0992.github.io/link/">Website</a> ·
  <a href="https://gowtham0992.github.io/link/getting-started.html">Quick start</a> ·
  <a href="https://gowtham0992.github.io/link/mcp.html">MCP setup</a> ·
  <a href="https://gowtham0992.github.io/link/skills.html">Skills</a> ·
  <a href="https://gowtham0992.github.io/link/cli.html">CLI</a> ·
  <a href="https://registry.modelcontextprotocol.io/?q=io.github.gowtham0992%2Flink">MCP Registry</a> ·
  <a href="https://pypi.org/project/link-mcp/">PyPI</a> ·
  <a href="https://github.com/gowtham0992/homebrew-link">Homebrew</a>
</p>

<p align="center">
  <a href="https://github.com/gowtham0992/link"><img src="https://img.shields.io/github/stars/gowtham0992/link?style=flat" alt="GitHub stars"></a>
  <a href="https://github.com/gowtham0992/link/actions/workflows/ci.yml"><img src="https://github.com/gowtham0992/link/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://registry.modelcontextprotocol.io/?q=io.github.gowtham0992%2Flink"><img src="https://img.shields.io/badge/MCP_Registry-io.github.gowtham0992%2Flink-blue" alt="MCP Registry"></a>
  <a href="https://pypi.org/project/link-mcp/"><img src="https://img.shields.io/pypi/v/link-mcp" alt="PyPI"></a>
</p>

## What Is Link?

Link is an open-source memory layer for local AI agents. Raw sources become an
inspectable Markdown wiki. Explicit "remember this" requests become reviewable
memories. Agents retrieve compact, source-backed context through the CLI, MCP,
official skills, or the local viewer without dumping the whole wiki into a chat
window.

The wiki is the storage layer. The product is durable memory that stays on your
machine, remains readable in plain files, and can be shared across multiple
agents instead of locked inside one vendor profile.

## How It Works

Link gives agents four simple moves:

1. **Capture** notes, transcripts, docs, screenshots, and project context in `raw/`.
2. **Structure** source-backed pages under `wiki/`.
3. **Remember** explicit preferences, decisions, facts, and project context as reviewable memory.
4. **Retrieve** compact query packets through the CLI, MCP, official skills, or the local web viewer.

Most agent sessions start from zero. You re-explain preferences, repo decisions,
project constraints, and why something matters. Link turns that repeated context
into local memory agents can query.

| Pain | Link's answer |
|------|---------------|
| Agents forget you between sessions. | Save reviewed preferences, decisions, facts, and project context. |
| Notes are private or messy. | Keep raw sources local, then turn them into source-backed Markdown. |
| Context windows are expensive. | Return compact query packets with provenance and follow-up actions. |
| Memory needs trust. | Every page and memory can be inspected, reviewed, archived, or forgotten. |

Link follows Andrej Karpathy's
[LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f):
keep knowledge outside the chat window, make claims inspectable, and let context
compound over time.

## Quick Start

Run the demo first. It creates a complete local wiki with raw sources, wiki
pages, one starter memory, graph data, and query packets ready to inspect.

macOS with Homebrew:

```bash
brew install gowtham0992/link/link
lnk try
lnk serve link-demo
```

The installed command is `lnk` because `link` is already a POSIX/macOS system
utility. From a source checkout, use `python3 link.py ...` instead.

Windows PowerShell:

```powershell
git clone https://github.com/gowtham0992/link.git
cd link
py link.py demo
py link.py next link-demo
py link.py serve link-demo
```

Source checkout on macOS/Linux:

```bash
git clone https://github.com/gowtham0992/link.git
cd link
python3 link.py demo
python3 link.py next link-demo
python3 link.py serve link-demo
```

Use `lnk try` for the shortest Homebrew proof loop. It creates the demo,
checks readiness, runs a compact query/brief proof, and prints the agent prompts
and viewer command. From source, use `python3 link.py try`.

The Homebrew formula is maintained in the public
[`gowtham0992/homebrew-link`](https://github.com/gowtham0992/homebrew-link) tap.

Open:

```text
http://127.0.0.1:3000
http://127.0.0.1:3000/graph
http://127.0.0.1:3000/health
```

The web viewer is for local use only. It binds to `127.0.0.1`, has no user
accounts or authentication, and should not be exposed to the internet unless you
add your own auth layer.

For the shortest guided proof path, run `lnk welcome link-demo`.

Try the value loop:

```bash
lnk query "why does Link help agents?" link-demo --budget small
lnk brief "working on agent memory" link-demo
lnk benchmark "agent memory" link-demo
lnk health link-demo
```

The `/health` page mirrors the readiness loop in the browser: validation state,
interrupted writes, memory review status, and copyable repair commands.
The viewer itself stays document-first: common paths are in the top nav, deeper
tools live under `more`, and structured wiki pages get a local contents outline
plus related-page links from the graph.
Home shows recently updated pages, while `/all` and search group results by page
type with chips for narrowing larger wikis.

From a source checkout, use `python3 link.py ...`:

```bash
python3 link.py query "why does Link help agents?" link-demo --budget small
python3 link.py brief "working on agent memory" link-demo
python3 link.py benchmark "agent memory" link-demo
python3 link.py health link-demo
```

The generated demo is the public proof wiki. The repo's root `wiki/` directory
is only a scaffold for local development and personal testing. Generated content
inside `wiki/`, `raw/`, and `link-demo/` is ignored by git so personal memory is
not published by accident.

For local scale checks from a source checkout, run:

```bash
python3 scripts/smoke_large_wiki.py --pages 10000
```

This generates a temporary synthetic wiki, verifies bounded graph/query payloads,
and reports cache timing, persistent-cache reuse, search, query, graph, and
health signals without touching your real Link wiki.
The public scale model is documented at
[Link Scale](https://gowtham0992.github.io/link/scale.html): what stays
bounded by default, how to measure your own wiki, and where the current local
limits are.

## Ways To Use Link

Pick the surface that matches how you work. They all read and write the same
local Markdown wiki.

These surfaces are independent. `lnk serve` / `serve.py` is only the local web
viewer. CLI commands, official skills, and MCP tools read the same `wiki/` files
directly, so Claude, Codex, Kiro, Cursor, or another agent can use Link even
when the web viewer is not running.

<table>
  <tr>
    <td width="33%">
      <strong>Web UI</strong><br>
      Read the local wiki, then review memory, ingest, graph, audits, captures, and explanations.<br><br>
      <a href="https://gowtham0992.github.io/link/ui.html"><img src="docs/assets/link-ui-tour.gif" alt="Link web UI walkthrough" width="270"></a>
    </td>
    <td width="33%">
      <strong>CLI</strong><br>
      Script readiness, query packets, briefs, validation, backup, benchmark, and repair.<br><br>
      <a href="https://gowtham0992.github.io/link/cli.html"><img src="docs/assets/link-cli-tour.gif" alt="Link CLI walkthrough" width="270"></a>
    </td>
    <td width="33%">
      <strong>MCP</strong><br>
      Let Codex, Claude, Cursor, Kiro, VS Code, Copilot, and other agents recall memory.<br><br>
      <a href="https://gowtham0992.github.io/link/mcp.html"><img src="docs/assets/link-mcp-agent-chat.gif" alt="Link MCP agent walkthrough" width="270"></a>
    </td>
  </tr>
</table>

Prefer skills instead of MCP? Link ships small, lazy-loadable CLI skills under
`skills/`. They let an agent use `lnk health`, `lnk query`, `lnk ingest-status`,
and `lnk remember` directly, without MCP setup or a running web viewer.

```text
skills/link-health/SKILL.md
skills/link-retrieve/SKILL.md
skills/link-ingest/SKILL.md
skills/link-memory/SKILL.md
```

Full guide: [Link Skills](https://gowtham0992.github.io/link/skills.html).

## Install For Your Agent

Run one installer from the cloned checkout:

```bash
bash integrations/codex/install.sh
bash integrations/kiro/install.sh
bash integrations/claude-code/install.sh
bash integrations/cursor/install.sh
bash integrations/copilot/install.sh
bash integrations/vscode/install.sh
bash integrations/antigravity/install.sh
```

Installers create or update `~/link`, install or upgrade `link-mcp`, write
lightweight agent instructions, and preserve existing wiki data on reinstall.
Use `--project` when a repo needs separate project memory.

On Windows, use the matching PowerShell installer:

```powershell
.\integrations\codex\install.ps1
.\integrations\kiro\install.ps1
.\integrations\claude-code\install.ps1
.\integrations\cursor\install.ps1
.\integrations\copilot\install.ps1
.\integrations\vscode\install.ps1
.\integrations\antigravity\install.ps1
```

Then ask your agent:

```text
is Link ready?
brief me from Link before we continue
ingest raw/notes.md into Link
remember that I prefer short release notes
query Link for the release process
what does Link remember about local personal memory?
```

If your agent already has instructions and you only need MCP wiring, use the
connection helper. It previews the exact config first; add `--write` when you
want Link to update the agent config file.

```bash
lnk connect codex ~/link
lnk connect codex ~/link --write
lnk connect kiro ~/link --write
lnk verify-mcp ~/link
```

<details>
<summary>MCP-only install</summary>

```bash
python3 -m pip install --upgrade link-m