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/#how">How it works</a> ·
  <a href="https://gowtham0992.github.io/link/#memory">Memory</a> ·
  <a href="https://gowtham0992.github.io/link/#tools">Tools &amp; CLI</a> ·
  <a href="https://gowtham0992.github.io/link/#setup">Setup</a> ·
  <a href="https://gowtham0992.github.io/link/getting-started.html">Docs</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>
  <a href="https://pepy.tech/projects/link-mcp"><img src="https://static.pepy.tech/personalized-badge/link-mcp?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="PyPI Downloads"></a>
  <a href="https://mcptoplist.com/server/io.github.gowtham0992%2Flink"><img src="https://mcptoplist.com/badge/io.github.gowtham0992%2Flink.svg" alt="MCP Toplist rank"></a>
</p>

<p align="center">
  <a href="https://gowtham0992.github.io/link/">
    <img src="docs/assets/link-remembers.svg" alt="Link demo: a preference said once in an agent session is captured automatically, approved by you, and recalled in a brand-new terminal the next day — from a plain Markdown file" width="840">
  </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.

<p align="center">
  <img src="docs/assets/link-aha.gif" alt="lnk recall finds a memory saved in completely different words — matched by meaning, not keywords" width="760">
</p>
<p align="center"><em>Ask in your own words; Link matches by meaning, not keywords. All local, all plain files.</em></p>

## 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.

## Why Link Is Different

Every other agent-memory system stores memory as embeddings in a vector
database or as an LLM-extracted graph. Link made four architectural
commitments those designs cannot bolt on:

1. **Memory you can read.** Every memory is a plain Markdown file — open it,
   grep it, git-diff it. If Link disappeared tomorrow, your memory is still yours.
2. **Review-gated writes.** Agents propose; you approve. Even the automatic
   session hooks capture proposals, never facts.
3. **No LLM in the memory layer.** Ingestion and recall are deterministic —
   nothing can hallucinate a fact into your memory, because there is no model
   in the write path.
4. **Provably local.** CI blocks outbound network code in the runtime, and the
   optional semantic models load offline-only after one explicit setup.

And the claims are measured, not asserted — see the benchmarks below. Named
comparisons against Mem0/OpenMemory, Zep/Graphiti, and Letta:
[Why Link?](https://gowtham0992.github.io/link/why-link.html)

## Benchmarks

Plain files with no LLM in the memory layer, measured against the systems
that have one everywhere:

| What | Link | For comparison |
|---|---|---|
| **LoCoMo end-to-end QA** — full 1,540 questions under [mem0's own open harness](https://github.com/mem0ai/memory-benchmarks) | **84.8%** | mem0's cloud platform: **83.2%** under the same judge — with GPT-5 writing their answers and a budget model (claude-haiku-4-5) writing Link's. Confirmed by a second, independent judge (Tencent Hunyuan 3): **85.5% vs 83.6%** |
| **LongMemEval evidence retrieval** — did the memory layer put the gold evidence in context? (deterministic, no LLM judge) | **99.4%** of 500 questions | of 102 answer failures, only 3 were retrieval misses — the rest happened with the evidence already retrieved |
| **Memory hygiene** — junk stored over a simulated multi-month session stream | **0%** (by construction, CI-enforced) | the same pipeline with governance off: 36.5% |
| **Memory poisoning** — 15 authored prompt-injection attacks on the capture pipeline (guardrail bypass, exfil conventions, credential planting, spoofed approvals) | **0** reach the inbox unlabeled; 0 false positives on benign directives (CI-enforced) | to our knowledge the only published adversarial benchmark on an agent-memory write path |
| **Bundled 1,176-case recall benchmark** — deterministic, runs offline in CI | hit@1 **0.749**, +rerank **0.839** | gates every change; a regression fails the build |

Every number ships with its config, judge model, caveats, and the
experiments that *lost* — including LongMemEval end-to-end, where we
re-judged both sides under the neutral Hunyuan 3 referee: mem0's GPT-5
answers score 91.0%, Link's budget-model answers 80.6%. Their published
number holds up, and the gap tracks the answering model, not the memory
layer — that's what the 99.4% evidence-retrieval row above isolates.
Full methodology and reproduction steps:
[benchmarks/RESULTS.md](benchmarks/RESULTS.md).

## Quick Start

Two commands: see it work, then make it yours.

```bash
brew install gowtham0992/link/link
lnk proof     # see the promise (~1 second, no setup)
lnk setup     # wire every agent you have — workspace, MCP, session hooks, one command
```

`lnk setup` detects the agents installed on your machine — Claude Code,
Codex, Cursor, Windsurf, Zed, Kiro, Gemini CLI — and wires them all at
once; Link is agent-agnostic by design (one MCP server, one workspace,
every agent reads the same memory). It is
idempotent: after any `brew upgrade`, run it again and everything —
workspace runtime, MCP provisioning, hooks — is refreshed. Prefer to wire
one agent explicitly? `lnk onboard --agent claude-code --write --hooks`
still does exactly that.

`lnk proof` creates a throwaway workspace, writes one reviewed memory, and
recalls it through the same path the CLI, skills, and MCP use — the core
promise (one local memory, reusable by different agents, no cloud profile) in
one second:

```text
Cross-agent memory continuity works
Memory: created and reviewed: Cross-agent Link proof
Recall: found through the same bounded recall path used by CLI, skills, and MCP.
Result: proof passed
```

`lnk onboard --agent claude-code --write` then creates `~/link`, provisions the
MCP runtime, and wires the agent — including the session hooks that capture
memory automatically as you work (swap `claude-code` for `codex`, `cursor`,
`kiro`, `copilot`, `antigravity`, or others). Drop `--write` to preview the
config without touching anything, or drop `--agent` to just create the
workspace.

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

Want the UI, graph, and source pages first? `lnk try && lnk serve link-demo`.
Windows, source checkout, MCP-only, and skill-first paths are in the
[First 10 Minutes guide](https://gowtham0992.github.io/link/getting-started.html).

Or seed your current repo as a separate step so the first real recall is not empty:

```bash
cd /path/to/your/project
lnk seed . ~/link
lnk query "what is this project about?" ~/link --budget small
```

`lnk seed` reads allowlisted project files such as `README.md`, `AGENTS.md`,
`CLAUDE.md`, `.cursorrules`, and editor rule files, blocks secret-looking
values, writes a source-backed project page, and rebuilds the graph. It does
not create durable memories; agents should still use reviewed memory propos