Link MCP server

Quick start

brew install gowtham0992/link/link   # or: pip install link-mcp
lnk setup                            # wires every agent you have

Then work normally. Tell an agent "remember that we deploy on Tuesdays", approve it once, and every other agent recalls it in a new session tomorrow.

lnk status                                   # is it wired up and being used?
lnk import claude-code                       # bring existing memory in
brew install --cask gowtham0992/link/linkbar # macOS menu bar app

Memory lives in plain Markdown you can open, and nothing becomes durable without your approval.

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 five 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.
5. Hold what you approved: rules are enforced before a tool call, memories about code are checked against the repository, and a receipt shows what each session was given.

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.
Agents read a rule and break it anyway.	A reviewed memory can carry a rule that asks for your OK, or blocks the call, before it runs.
Memory goes stale as the code moves on.	Memories that name files, scripts, dependencies or functions are checked against the repository and flagged, not believed.
You cannot tell what the agent was given.	lnk receipt lists every memory that reached a session and whether it arrived whole.

Link follows Andrej Karpathy's LLM Wiki pattern: 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 five 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.
5. Memory that holds when the agent acts. A memory you reviewed can carry a rule (ask command: git push --force, deny write: migrations/**) that is checked before the agent's tool call, with no model and under a millisecond. Memories about code are re-read against your repository and flagged when the code moved on. Memories surface when the agent opens the file they describe, lnk compile writes reviewed memory into the files every agent already reads, and a receipt proves what reached each session.

And the claims are measured, not asserted — see the benchmarks below. Named comparisons against Mem0/OpenMemory, Zep/Graphiti, and Letta: Why Link?

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	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: 35.7%
Memory poisoning — 18 authored prompt-injection attacks on the capture pipeline (guardrail bypass, exfil conventions, credential planting, spoofed approvals, MemGhost-class untrusted-channel writes)	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
Token economics — real recall packets, measured through the query path	1,697–3,752 tokens per recall (micro→large budget); a 64× larger store grows the packet 1.56×, and the last quadrupling moves it 0.3%	bounded by the budget you ask for, not by how much you have remembered; CI-enforced. Over MCP, the first response of a session also carries a one-time memory brief, bounded to a hard 4,000-character budget (~365 tokens of overhead, measured) — see RESULTS.md
Enforced rules — 17 forbidden tool calls, including shell disguises (cd x && sudo …, quoting, bash -c), against 34 ordinary coding-agent calls	17 of 17 caught, 0 of 34 stopped, under 0.2 ms per decision	a rule acts only after you review it; the agent cannot approve, clear or bypass one
Staleness checks — memories and instruction files (AGENTS.md, CLAUDE.md, Cursor rules…) checked against the repository	0 false flags: 345 memory references in Link's own docs and 604 instruction-file references across eight public repositories; every planted deletion caught	a reference is reported only when git history shows the thing existed
Bundled 1,176-case recall benchmark — deterministic, no network, no LLM	pip default (lexical) hit@1 0.671; lnk setup provisions the fast local tier by default: 0.740; optional quality tier 0.789, plus rerank 0.798	reproducible with one command; CI runs the suite and gates dataset integrity, not the score

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.

Memory You Can Take Anywhere — And Prove Is Working

Three questions every memory system should answer, and how Link answers them with mechanisms instead of promises:

"Is it on all my machines?" lnk sync moves reviewed memory through a git remote you control — a private GitHub repo, a homelab bare repo — with no server and no account. Secrets are scanned before anything leaves, conflicts become review items instead of git markers, and private captures never sync. lnk team-sync runs a shared team brain on the same rails.

"What did I believe back then?" Ask in plain language: lnk recall "where does local data live in March" returns what was true then, reconstructed from the dated files and their supersede lineage — while the same question without the date returns today's truth. Deterministic: a regex and a calendar, no model. Point-in-time accuracy from plain language: 1.00 on the hygiene benchmark's revised facts, identical to asking with an ISO date.

"Is my agent actually using this?" The question most memory systems cannot answer about themselves. Link records retrievals locally — session briefs pushed to agents, recalls they chose to make — and lnk wins answers with counts, while lnk digest reports the weekly story including memories that have never been retrieved. The ledger stores which memory was read and when, never what you asked; it never syncs, and LINK_USAGE=off disables it. And memory reaches every agent, not just the hooked ones: the first MCP tool response of a session carries the brief, whatever tool was called.

First Run, In Detail

The quick start above is the whole install. This is what each step does.

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

Already have memory scattered across tools? Bring it home as reviewable proposals — nothing is auto-accepted:

lnk import claude-code   # or: cursor, codex, file --file chatgpt.txt

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:

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 --hooks creates ~/link, provisions the MCP runtime, and wires the agent. Swap claude-code for codex, cursor, kiro, copilot, antigravity, windsurf, zed or vscode. Session hooks - a brief at session start, proposals captured at session end - exist for Claude Code, Cursor and Codex (Codex has no session-end event, so it gets the start brief only). The other agents get memory through MCP, where the first tool response of a session carries the same brief. Drop --write to preview without touching anything, or drop --agent to just create the workspace. lnk disconnect <agent> --write takes Link back out: its MCP entry and hooks, nothing else.

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.

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

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 proposals for preferences and decisions.

The Homebrew formula is maintained in the public gowtham0992/homebrew-link tap.

Open:

http://127.0.0.1:3000
http://127.0.0.1:3000/onboard
http://127.0.0.1:3000/graph
http://127.0.0.1:3000/health

Use /onboard when you want the same first-run checklist in the local UI: readiness, project context seeding, first memory, agent wiring, and starter prompts. 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.

Try the value loop:

lnk start link-demo --task "working on agent memory"
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

lnk benchmark reports both performance and value evidence: cache/search/query timings, graph payload shape, and an estimate of how much broad wiki context the bounded Link packet avoided sending to an agent.

The /health page mirrors the readiness loop in the browser: validation state, interrupted writes, memory review status, and copyable repair commands. The viewer stays document-first — common paths in the top nav, deeper tools under more, and a contents outline plus graph-related links on structured pages.

The generated demo is the public proof wiki. Generated content inside wiki/, raw/, and link-demo/ is ignored by git so personal memory is not published by accident.

LinkBar — the menu bar app (macOS)

Link's memory, ambient. LinkBar puts the review gate in your menu bar: a global palette (⌥⌘M) to recall or remember from any app, native notifications with one-tap Accept when a session capture lands, a live pulse while agents are writing, a browser over every memory file, and a status dashboard that flags memories naming files your repository no longer has — all running on the same reviewed lnk commands as the CLI. Pick the workspace in Settings; it defaults to ~/link.

brew install --cask gowtham0992/link/linkbar

Unsigned on purpose (no Apple fee inflating anything): the cask strips the quarantine flag on install, so it opens like any app. Building from source instead: cd apps/LinkBar && bash Scripts/bundle.sh --install.

Killer Demo: One Memory, Two Agents

This is the moment Link is built for:

1. In one agent, say:

   remember that I prefer local, source-backed memory for AI agents
   

2. In another agent connected to the same ~/link workspace, say:

   start with Link before we continue
   what does Link remember about local agent memory?
   

3. The second agent should recall the reviewed memory from local Markdown instead of asking you to repeat yourself.

For a clean automated version of the same idea, run:

lnk proof

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.

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, lnk session-end, and lnk remember directly, without MCP setup or a running web viewer.

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

Full guide: Link Skills.

Install For Your Agent

Run one installer from the cloned checkout:

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:

.\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:

is Link ready?
start with Link before we continue
seed this project into Link
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?
end this session with Link memory proposals

For CLI-first agents or Link skills, use the same startup loop directly:

lnk seed . ~/link
lnk start ~/link --task "working on Link release"
lnk session-end session-notes.md ~/link --limit 3

If you want one guided setup for a real workspace and an agent, use lnk onboard --agent AGENT. If your agent already has instructions and you only need MCP wiring, use the lower-level connection helper. Both preview the exact config first; add --write when you want Link to update the agent config file.

lnk onboard --agent codex
lnk onboard --agent codex --write
lnk connect codex ~/link
lnk connect codex ~/link --write
lnk connect kiro ~/link --write
lnk verify-mcp ~/link

For agents with session-hook support — Claude Code, Codex, and Cursor — add --hooks (works with lnk onboard too) to make the memory loop automatic: the brief is injected at session start and proposal-only notes are captured at session end, so memory no longer depends on the agent remembering to call Link. Empty sessions and duplicate end events are skipped, and when the backlog builds up the brief nudges the agent to offer a read-only lnk consolidate pass. On Claude Code the hooks also run before shell and file tool calls: a reviewed memory's enforced rules are checked there, and memories anchored to the file being read or edited are surfaced at that moment; on Cursor the shell-command check runs the same way. lnk receipt shows what actually arrived in each session. Durable memory still requires your approval. Codex and Cursor hook support is new (wired to their documented schemas — report issues).

lnk connect claude-code ~/link --hooks --write
lnk connect codex ~/link --hooks --write    # session-start brief (Codex has no session-end event)
lnk connect cursor ~/link --hooks --write
lnk consolidate ~/link                      # read-only backlog plan, apply only with approval