Skip to content
Back to search

link

Local personal memory for LLM agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gowtham0992--link/badge.svg)](/listings/gowtham0992--link)

HTML

<a href="/listings/gowtham0992--link"><img src="/api/listings/gowtham0992--link/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 783 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="logo.svg" alt="Link" width="128">
  3. </p>
  4. <h1 align="center">Link</h1>
  5. <h2 align="center">Local memory for AI agents.</h2>
  6. <p align="center">
  7. Link gives Codex, Claude, Cursor, Kiro, VS Code, Copilot, Antigravity, and
  8. other local agents the same source-backed memory, stored locally as Markdown.
  9. </p>
  10. <p align="center">
  11. <a href="https://gowtham0992.github.io/link/">Website</a> ·
  12. <a href="https://gowtham0992.github.io/link/#how">How it works</a> ·
  13. <a href="https://gowtham0992.github.io/link/#memory">Memory</a> ·
  14. <a href="https://gowtham0992.github.io/link/#tools">Tools &amp; CLI</a> ·
  15. <a href="https://gowtham0992.github.io/link/#setup">Setup</a> ·
  16. <a href="https://gowtham0992.github.io/link/getting-started.html">Docs</a> ·
  17. <a href="https://registry.modelcontextprotocol.io/?q=io.github.gowtham0992%2Flink">MCP Registry</a> ·
  18. <a href="https://pypi.org/project/link-mcp/">PyPI</a> ·
  19. <a href="https://github.com/gowtham0992/homebrew-link">Homebrew</a>
  20. </p>
  21. <p align="center">
  22. <a href="https://github.com/gowtham0992/link"><img src="https://img.shields.io/github/stars/gowtham0992/link?style=flat" alt="GitHub stars"></a>
  23. <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>
  24. <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>
  25. <a href="https://pypi.org/project/link-mcp/"><img src="https://img.shields.io/pypi/v/link-mcp" alt="PyPI"></a>
  26. <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>
  27. <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>
  28. </p>
  29. <p align="center">
  30. <a href="https://gowtham0992.github.io/link/">
  31. <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">
  32. </a>
  33. </p>
  34. ## Quick start
  35. ```bash
  36. brew install gowtham0992/link/link # or: pip install link-mcp
  37. lnk setup # wires every agent you have
  38. ```
  39. Then work normally. Tell an agent "remember that we deploy on Tuesdays",
  40. approve it once, and every other agent recalls it in a new session tomorrow.
  41. ```bash
  42. lnk status # is it wired up and being used?
  43. lnk import claude-code # bring existing memory in
  44. brew install --cask gowtham0992/link/linkbar # macOS menu bar app
  45. ```
  46. Memory lives in plain Markdown you can open, and nothing becomes durable
  47. without your approval.
  48. ## What Is Link?
  49. Link is an open-source memory layer for local AI agents. Raw sources become an
  50. inspectable Markdown wiki. Explicit "remember this" requests become reviewable
  51. memories. Agents retrieve compact, source-backed context through the CLI, MCP,
  52. official skills, or the local viewer without dumping the whole wiki into a chat
  53. window.
  54. The wiki is the storage layer. The product is durable memory that stays on your
  55. machine, remains readable in plain files, and can be shared across multiple
  56. agents instead of locked inside one vendor profile.
  57. <p align="center">
  58. <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">
  59. </p>
  60. <p align="center"><em>Ask in your own words; Link matches by meaning, not keywords. All local, all plain files.</em></p>
  61. ## How It Works
  62. Link gives agents five simple moves:
  63. 1. **Capture** notes, transcripts, docs, screenshots, and project context in `raw/`.
  64. 2. **Structure** source-backed pages under `wiki/`.
  65. 3. **Remember** explicit preferences, decisions, facts, and project context as reviewable memory.
  66. 4. **Retrieve** compact query packets through the CLI, MCP, official skills, or the local web viewer.
  67. 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.
  68. Most agent sessions start from zero. You re-explain preferences, repo decisions,
  69. project constraints, and why something matters. Link turns that repeated context
  70. into local memory agents can query.
  71. | Pain | Link's answer |
  72. |------|---------------|
  73. | Agents forget you between sessions. | Save reviewed preferences, decisions, facts, and project context. |
  74. | Notes are private or messy. | Keep raw sources local, then turn them into source-backed Markdown. |
  75. | Context windows are expensive. | Return compact query packets with provenance and follow-up actions. |
  76. | Memory needs trust. | Every page and memory can be inspected, reviewed, archived, or forgotten. |
  77. | 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. |
  78. | 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. |
  79. | You cannot tell what the agent was given. | `lnk receipt` lists every memory that reached a session and whether it arrived whole. |
  80. Link follows Andrej Karpathy's
  81. [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f):
  82. keep knowledge outside the chat window, make claims inspectable, and let context
  83. compound over time.
  84. ## Why Link Is Different
  85. Every other agent-memory system stores memory as embeddings in a vector
  86. database or as an LLM-extracted graph. Link made five architectural
  87. commitments those designs cannot bolt on:
  88. 1. **Memory you can read.** Every memory is a plain Markdown file — open it,
  89. grep it, git-diff it. If Link disappeared tomorrow, your memory is still yours.
  90. 2. **Review-gated writes.** Agents propose; you approve. Even the automatic
  91. session hooks capture proposals, never facts.
  92. 3. **No LLM in the memory layer.** Ingestion and recall are deterministic —
  93. nothing can hallucinate a fact into your memory, because there is no model
  94. in the write path.
  95. 4. **Provably local.** CI blocks outbound network code in the runtime, and the
  96. optional semantic models load offline-only after one explicit setup.
  97. 5. **Memory that holds when the agent acts.** A memory you reviewed can carry a
  98. rule (`ask command: git push --force`, `deny write: migrations/**`) that is
  99. checked before the agent's tool call, with no model and under a
  100. millisecond. Memories about code are re-read against your repository and
  101. flagged when the code moved on. Memories surface when the agent opens the
  102. file they describe, `lnk compile` writes reviewed memory into the files
  103. every agent already reads, and a receipt proves what reached each session.
  104. And the claims are measured, not asserted — see the benchmarks below. Named
  105. comparisons against Mem0/OpenMemory, Zep/Graphiti, and Letta:
  106. [Why Link?](https://gowtham0992.github.io/link/why-link.html)
  107. ## Benchmarks
  108. Plain files with no LLM in the memory layer, measured against the systems
  109. that have one everywhere:
  110. | What | Link | For comparison |
  111. |---|---|---|
  112. | **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%** |
  113. | **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 |
  114. | **Memory hygiene** — junk stored over a simulated multi-month session stream | **0%** (by construction, CI-enforced) | the same pipeline with governance off: 35.7% |
  115. | **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 |
  116. | **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 |
  117. | **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 |
  118. | **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 |
  119. | **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 |
  120. Every number ships with its config, judge model, caveats, and the
  121. experiments that *lost* — including LongMemEval end-to-end, where we
  122. re-judged both sides under the neutral Hunyuan 3 referee: mem0's GPT-5
  123. answers score 91.0%, Link's budget-model answers 80.6%. Their published
  124. number holds up, and the gap tracks the answering model, not the memory
  125. layer — that's what the 99.4% evidence-retrieval row above isolates.
  126. Full methodology and reproduction steps:
  127. [benchmarks/RESULTS.md](benchmarks/RESULTS.md).
  128. ## Memory You Can Take Anywhere — And Prove Is Working
  129. Three questions every memory system should answer, and how Link answers
  130. them with mechanisms instead of promises:
  131. **"Is it on all my machines?"** `lnk sync` moves reviewed memory through
  132. a git remote *you* control — a private GitHub repo, a homelab bare repo —
  133. with no server and no account. Secrets are scanned before anything
  134. leaves, conflicts become review items instead of git markers, and private
  135. captures never sync. `lnk team-sync` runs a shared team brain on the same
  136. rails.
  137. **"What did I believe back then?"** Ask in plain language: `lnk recall
  138. "where does local data live in March"` returns what was true *then*,
  139. reconstructed from the dated files and their supersede lineage — while
  140. the same question without the date returns today's truth. Deterministic:
  141. a regex and a calendar, no model. Point-in-time accuracy from plain
  142. language: 1.00 on the hygiene benchmark's revised facts, identical to
  143. asking with an ISO date.
  144. **"Is my agent actually using this?"** The question most memory systems
  145. cannot answer about themselves. Link records retrievals locally — session
  146. briefs pushed to agents, recalls they chose to make — and `lnk wins`
  147. answers with counts, while `lnk digest` reports the weekly story
  148. including memories that have *never* been retrieved. The ledger stores
  149. which memory was read and when, never what you asked; it never syncs, and
  150. `LINK_USAGE=off` disables it. And memory reaches every agent, not just
  151. the hooked ones: the first MCP tool response of a session carries the
  152. brief, whatever tool was called.
  153. ## First Run, In Detail
  154. The quick start above is the whole install. This is what each step does.
  155. ```bash
  156. brew install gowtham0992/link/link
  157. lnk proof # see the promise (~1 second, no setup)
  158. lnk setup # wire every agent you have — workspace, MCP, session hooks, one command
  159. ```
  160. Already have memory scattered across tools? Bring it home as reviewable
  161. proposals — nothing is auto-accepted:
  162. ```bash
  163. lnk import claude-code # or: cursor, codex, file --file chatgpt.txt
  164. ```
  165. `lnk setup` detects the agents installed on your machine — Claude Code,
  166. Codex, Cursor, Windsurf, Zed, Kiro, Gemini CLI — and wires them all at
  167. once; Link is agent-agnostic by design (one MCP server, one workspace,
  168. every agent reads the same memory). It is
  169. idempotent: after any `brew upgrade`, run it again and everything —
  170. workspace runtime, MCP provisioning, hooks — is refreshed. Prefer to wire
  171. one agent explicitly? `lnk onboard --agent claude-code --write --hooks`
  172. still does exactly that.
  173. `lnk proof` creates a throwaway workspace, writes one reviewed memory, and
  174. recalls it through the same path the CLI, skills, and MCP use — the core
  175. promise (one local memory, reusable by different agents, no cloud profile) in
  176. one second:
  177. ```text
  178. Cross-agent memory continuity works
  179. Memory: created and reviewed: Cross-agent Link proof
  180. Recall: found through the same bounded recall path used by CLI, skills, and MCP.
  181. Result: proof passed
  182. ```
  183. `lnk onboard --agent claude-code --write --hooks` creates `~/link`, provisions
  184. the MCP runtime, and wires the agent. Swap `claude-code` for `codex`,
  185. `cursor`, `kiro`, `copilot`, `antigravity`, `windsurf`, `zed` or `vscode`.
  186. Session hooks - a brief at session start, proposals captured at session end -
  187. exist for Claude Code, Cursor and Codex (Codex has no session-end event, so it
  188. gets the start brief only). The other agents get memory through MCP, where the
  189. first tool response of a session carries the same brief. Drop `--write` to
  190. preview without touching anything, or drop `--agent` to just create the
  191. workspace. `lnk disconnect <agent> --write` takes Link back out: its MCP entry
  192. and hooks, nothing else.
  193. The installed command is `lnk` because `link` is already a POSIX/macOS system
  194. utility. From a source checkout, use `python3 link.py ...` instead.
  195. Want the UI, graph, and source pages first? `lnk try && lnk serve link-demo`.
  196. Windows, source checkout, MCP-only, and skill-first paths are in the
  197. [First 10 Minutes guide](https://gowtham0992.github.io/link/getting-started.html).
  198. Or seed your current repo as a separate step so the first real recall is not empty:
  199. ```bash
  200. cd /path/to/your/project
  201. lnk seed . ~/link
  202. lnk query "what is this project about?" ~/link --budget small
  203. ```
  204. `lnk seed` reads allowlisted project files such as `README.md`, `AGENTS.md`,
  205. `CLAUDE.md`, `.cursorrules`, and editor rule files, blocks secret-looking
  206. values, writes a source-backed project page, and rebuilds the graph. It does
  207. not create durable memories; agents should still use reviewed memory proposals
  208. for preferences and decisions.
  209. The Homebrew formula is maintained in the public
  210. [`gowtham0992/homebrew-link`](https://github.com/gowtham0992/homebrew-link) tap.
  211. Open:
  212. ```text
  213. http://127.0.0.1:3000
  214. http://127.0.0.1:3000/onboard
  215. http://127.0.0.1:3000/graph
  216. http://127.0.0.1:3000/health
  217. ```
  218. Use `/onboard` when you want the same first-run checklist in the local UI:
  219. readiness, project context seeding, first memory, agent wiring, and starter
  220. prompts. The web viewer is for local use only. It binds to `127.0.0.1`, has no user
  221. accounts or authentication, and should not be exposed to the internet unless you
  222. add your own auth layer.
  223. Try the value loop:
  224. ```bash
  225. lnk start link-demo --task "working on agent memory"
  226. lnk query "why does Link help agents?" link-demo --budget small
  227. lnk brief "working on agent memory" link-demo
  228. lnk benchmark "agent memory" link-demo
  229. lnk health link-demo
  230. ```
  231. `lnk benchmark` reports both performance and value evidence: cache/search/query
  232. timings, graph payload shape, and an estimate of how much broad wiki context the
  233. bounded Link packet avoided sending to an agent.
  234. The `/health` page mirrors the readiness loop in the browser: validation state,
  235. interrupted writes, memory review status, and copyable repair commands. The
  236. viewer stays document-first — common paths in the top nav, deeper tools under
  237. `more`, and a contents outline plus graph-related links on structured pages.
  238. The generated demo is the public proof wiki. Generated content inside `wiki/`,
  239. `raw/`, and `link-demo/` is ignored by git so personal memory is not published
  240. by accident.
  241. ## LinkBar — the menu bar app (macOS)
  242. Link's memory, ambient. LinkBar puts the review gate in your menu bar: a
  243. global palette (⌥⌘M) to recall or remember from any app, native
  244. notifications with one-tap Accept when a session capture lands, a live
  245. pulse while agents are writing, a browser over every memory file, and a
  246. status dashboard that flags memories naming files your repository no
  247. longer has — all running on the same reviewed `lnk` commands as the CLI.
  248. Pick the workspace in Settings; it defaults to `~/link`.
  249. <p align="center">
  250. <img src="docs/assets/linkbar-tour.gif" alt="LinkBar cycling through its tabs: the review inbox showing the rule a memory will enforce before you approve it and the last session's receipt, the memory browser, and settings" width="424">
  251. </p>
  252. ```bash
  253. brew install --cask gowtham0992/link/linkbar
  254. ```
  255. Unsigned on purpose (no Apple fee inflating anything): the cask strips
  256. the quarantine flag on install, so it opens like any app. Building from
  257. source instead: `cd apps/LinkBar && bash Scripts/bundle.sh --install`.
  258. ## Killer Demo: One Memory, Two Agents
  259. This is the moment Link is built for:
  260. 1. In one agent, say:
  261. ```text
  262. remember that I prefer local, source-backed memory for AI agents
  263. ```
  264. 2. In another agent connected to the same `~/link` workspace, say:
  265. ```text
  266. start with Link before we continue
  267. what does Link remember about local agent memory?
  268. ```
  269. 3. The second agent should recall the reviewed memory from local Markdown
  270. instead of asking you to repeat yourself.
  271. For a clean automated version of the same idea, run:
  272. ```bash
  273. lnk proof
  274. ```
  275. ## Ways To Use Link
  276. Pick the surface that matches how you work. They all read and write the same
  277. local Markdown wiki.
  278. These surfaces are independent. `lnk serve` / `serve.py` is only the local web
  279. viewer. CLI commands, official skills, and MCP tools read the same `wiki/` files
  280. directly, so Claude, Codex, Kiro, Cursor, or another agent can use Link even
  281. when the web viewer is not running.
  282. <table>
  283. <tr>
  284. <td width="33%">
  285. <strong><a href="https://gowtham0992.github.io/link/ui.html">Web UI</a></strong><br>
  286. Read the local wiki, then review memory, ingest, graph, audits, captures, and explanations.
  287. </td>
  288. <td width="33%">
  289. <strong><a href="https://gowtham0992.github.io/link/cli.html">CLI</a></strong><br>
  290. Script readiness, query packets, briefs, validation, backup, context-savings benchmark, and repair.
  291. </td>
  292. <td width="33%">
  293. <strong><a href="https://gowtham0992.github.io/link/mcp.html">MCP</a></strong><br>
  294. Let Codex, Claude, Cursor, Kiro, VS Code, Copilot, and other agents recall memory.
  295. </td>
  296. </tr>
  297. </table>
  298. <p align="center">
  299. <img src="docs/assets/link-ui-tour.gif" alt="Link local console tour: home, memory dashboard, health, and graph" width="840">
  300. </p>
  301. <p align="center"><em>The local web viewer: browse source-backed memory and explore the knowledge graph — all on <code>127.0.0.1</code>, no accounts, no backend.</em></p>
  302. Prefer skills instead of MCP? Link ships small, lazy-loadable CLI skills under
  303. `skills/`. They let an agent use `lnk health`, `lnk query`, `lnk ingest-status`,
  304. `lnk session-end`, and `lnk remember` directly, without MCP setup or a running
  305. web viewer.
  306. ```text
  307. skills/link-health/SKILL.md
  308. skills/link-retrieve/SKILL.md
  309. skills/link-ingest/SKILL.md
  310. skills/link-memory/SKILL.md
  311. ```
  312. Full guide: [Link Skills](https://gowtham0992.github.io/link/skills.html).
  313. ## Install For Your Agent
  314. Run one installer from the cloned checkout:
  315. ```bash
  316. bash integrations/codex/install.sh
  317. bash integrations/kiro/install.sh
  318. bash integrations/claude-code/install.sh
  319. bash integrations/cursor/install.sh
  320. bash integrations/copilot/install.sh
  321. bash integrations/vscode/install.sh
  322. bash integrations/antigravity/install.sh
  323. ```
  324. Installers create or update `~/link`, install or upgrade `link-mcp`, write
  325. lightweight agent instructions, and preserve existing wiki data on reinstall.
  326. Use `--project` when a repo needs separate project memory.
  327. On Windows, use the matching PowerShell installer:
  328. ```powershell
  329. .\integrations\codex\install.ps1
  330. .\integrations\kiro\install.ps1
  331. .\integrations\claude-code\install.ps1
  332. .\integrations\cursor\install.ps1
  333. .\integrations\copilot\install.ps1
  334. .\integrations\vscode\install.ps1
  335. .\integrations\antigravity\install.ps1
  336. ```
  337. Then ask your agent:
  338. ```text
  339. is Link ready?
  340. start with Link before we continue
  341. seed this project into Link
  342. ingest raw/notes.md into Link
  343. remember that I prefer short release notes
  344. query Link for the release process
  345. what does Link remember about local personal memory?
  346. end this session with Link memory proposals
  347. ```
  348. For CLI-first agents or Link skills, use the same startup loop directly:
  349. ```bash
  350. lnk seed . ~/link
  351. lnk start ~/link --task "working on Link release"
  352. lnk session-end session-notes.md ~/link --limit 3
  353. ```
  354. If you want one guided setup for a real workspace and an agent, use
  355. `lnk onboard --agent AGENT`. If your agent already has instructions and you only
  356. need MCP wiring, use the lower-level connection helper. Both preview the exact
  357. config first; add `--write` when you want Link to update the agent config file.
  358. ```bash
  359. lnk onboard --agent codex
  360. lnk onboard --agent codex --write
  361. lnk connect codex ~/link
  362. lnk connect codex ~/link --write
  363. lnk connect kiro ~/link --write
  364. lnk verify-mcp ~/link
  365. ```
  366. For agents with session-hook support — Claude Code, Codex, and Cursor — add
  367. `--hooks` (works with `lnk onboard` too) to make the memory loop automatic:
  368. the brief is injected at session start and proposal-only notes are captured at
  369. session end, so memory no longer depends on the agent remembering to call
  370. Link. Empty sessions and duplicate end events are skipped, and when the
  371. backlog builds up the brief nudges the agent to offer a read-only
  372. `lnk consolidate` pass. On Claude Code the hooks also run before shell and
  373. file tool calls: a reviewed memory's enforced rules are checked there, and
  374. memories anchored to the file being read or edited are surfaced at that
  375. moment; on Cursor the shell-command check runs the same way. `lnk receipt`
  376. shows what actually arrived in each session. Durable memory still requires
  377. your approval. Codex and Cursor hook support is new (wired to their
  378. documented schemas — report issues).
  379. ```bash
  380. lnk connect claude-code ~/link --hooks --write
  381. lnk connect codex ~/link --hooks --write # session-start brief (Codex has no session-end event)
  382. lnk connect cursor ~/link --hooks --write
  383. lnk consolidate ~/link # read-only backlog plan, apply only with approval
  384. ```
  385. ### Optional: hybrid semantic recall (still fully local)
  386. Lexical recall is always the default and the fallback. Paraphrase matching is
  387. opt-in: after the two setup commands below, "how should I structure my pull
  388. requests" finds a memory saved about commit style. Until then, recall matches
  389. on shared words, and a miss tells you how to turn paraphrase matching on.
  390. Installing the optional semantic extra adds a small local static-embedding
  391. model. Recall never touches the
  392. network: the model loads offline-only after a one-time explicit setup,
  393. embeddings live in plain JSON under `.link-cache/`, similarity runs in-process
  394. with no vector database, and semantic-only matches carry capped confidence
  395. labels so agents verify before trusting them.
  396. ```bash
  397. pip install "link-mcp[semantic]" # fast tier: tiny static model, instant load
  398. pip install "link-mcp[semantic-quality]" # quality tier: contextual model, best recall
  399. lnk semantic ~/link --setup # one-time model fetch, with your approval
  400. lnk semantic ~/link # status: lexical only vs hybrid, active tier
  401. python3 -m link_mcp --semantic-setup --wiki ~/link/wiki # MCP-only installs
  402. ```
  403. Measured, not asserted: on the bundled 1,176-case benchmark, the quality
  404. tier lifts token-overlap hit@1 from 0.671 to 0.789 and finds half of the
  405. pure paraphrases (zero token overlap) in the top 5, where lexical recall
  406. finds 6%, at ~11 ms per recall with no service or vector database. On the
  407. third-party LoCoMo retrieval track (1,536 evidence-annotated questions over
  408. 5,882 conversation turns), hybrid recall lifts any-evidence hit@10 from
  409. 0.716 to 0.779, and the opt-in rerank tier to 0.826 with hit@1 0.453.
  410. Without the reranker, lexical recall is the stronger top-5 on LoCoMo;
  411. RESULTS.md says why. Full methodology, honest limitations, and
  412. reproduction steps: [benchmarks/RESULTS.md](benchmarks/RESULTS.md).
  413. <details>
  414. <summary>MCP-only install</summary>
  415. ```bash
  416. python3 -m pip install --upgrade link-mcp
  417. python3 -m link_mcp --version
  418. ```
  419. ```json
  420. {
  421. "mcpServers": {
  422. "link": {
  423. "command": "python3",
  424. "args": ["-m", "link_mcp", "--wiki", "~/link/wiki", "--surface", "slim"]
  425. }
  426. }
  427. }
  428. ```
  429. `--surface slim` is the recommended MCP surface for agents: six obvious tools
  430. for recall, remember, ingest, review, status, and admin escape hatches. The full
  431. compatibility surface is still available with `--surface full`.
  432. On macOS/Homebrew Python, if pip reports `externally-managed-environment`, use a
  433. dedicated venv:
  434. ```bash
  435. python3 -m venv ~/.link-mcp-venv
  436. ~/.link-mcp-venv/bin/python -m pip install --upgrade pip link-mcp
  437. ```
  438. Full setup: [MCP guide](https://gowtham0992.github.io/link/mcp.html).
  439. </details>
  440. Obsidian users can import an existing vault into `raw/` for agent ingest, or
  441. open `~/link/wiki` directly as a vault for editing Link pages:
  442. ```bash
  443. lnk init ~/link
  444. lnk import-obsidian ~/Documents/ObsidianVault ~/link
  445. ```
  446. See the [Obsidian guide](https://gowtham0992.github.io/link/obsidian.html) for
  447. the import, edit, and validation loop.
  448. ## Storage Model
  449. Under the hood, Link separates source-backed knowledge from durable agent memory:
  450. 1. Drop raw notes, transcripts, articles, and project context into `raw/`.
  451. 2. Agents compile those sources into inspectable pages under `wiki/`.
  452. 3. Explicit "remember" requests become reviewable memory pages.
  453. 4. Queries retrieve compact agent context from both the wiki and memory layer.
  454. <p align="center">
  455. <img src="docs/assets/link-memory-flow.svg" alt="Link architecture: raw sources become wiki knowledge, explicit remembers become reviewed memory, and agents retrieve compact context" width="820">
  456. </p>
  457. The storage model is plain and inspectable:
  458. | Layer | What lives there |
  459. |-------|------------------|
  460. | `raw/` | Original notes, transcripts, articles, PDFs, screenshots, and project files. |
  461. | `wiki/` | Source-backed pages, concepts, entities, explorations, comparisons, and memories. |
  462. | Agent interfaces | CLI, skills, MCP, and local viewer paths that avoid dumping the whole wiki into context. |
  463. If a raw file was already ingested and later edited, `lnk ingest-status` marks it
  464. as stale and tells your agent to refresh the existing source page instead of
  465. creating a duplicate.
  466. Structured exports with a supported schema can use deterministic ingestion.
  467. Planning is read-only; applying stages the complete result, rebuilds the graph,
  468. validates it, and records output ownership before changing the live wiki:
  469. ```bash
  470. lnk ingest raw/chezmoi-docs/export.jsonl ~/link \
  471. --adapter chezmoi-docs-graph-v1 \
  472. --exclude "Reference / Release history"
  473. lnk ingest raw/chezmoi-docs/export.jsonl ~/link \
  474. --adapter chezmoi-docs-graph-v1 \
  475. --exclude "Reference / Release history" \
  476. --apply
  477. ```
  478. Later runs update only adapter-owned outputs. Manual edits become conflicts.
  479. `--replace-unmanaged` is required for a first migration over existing pages,
  480. and `--prune` is required to retire managed pages no longer in the plan.
  481. Arbitrary notes and articles continue through agent-authored ingest because
  482. their useful structure cannot be inferred safely from a file format alone.
  483. ## What Agents Get
  484. When an agent uses Link through the recommended MCP surface, it gets six
  485. model-facing tools. CLI and skill workflows call the same core behavior through
  486. `lnk`.
  487. - `status`: readiness, schema state, validation, interrupted writes, and safe
  488. next actions.
  489. - `recall`: the one read path for startup briefs, answer-ready query packets,
  490. wiki search, graph context, token budgets, and follow-up actions. Every
  491. recalled memory carries a `confidence` label (`strong`, `moderate`, `weak`)
  492. and a `match` field (`lexical`, `semantic`, `hybrid` when the optional local
  493. semantic tier is installed), so agents verify weak or paraphrase matches with
  494. the user instead of trusting them.
  495. - `remember`: durable local memory only after explicit user approval, with
  496. duplicate/conflict checks, provenance, review state, visibility, optional
  497. enforce rules that act on tool calls once you review the memory, optional
  498. `review_after`, and optional `expires_at`.
  499. - `ingest`: exact next steps for raw files, source safety, stale ingest
  500. detection, validation, and rebuild checks.
  501. - `review`: memory inbox, profile, audit, log, explain, archive, restore,
  502. forget, and lifecycle review workflows — plus `review(action="consolidate")`,
  503. a read-only backlog plan applied only with per-action user approval.
  504. - `admin`: the escape hatch for backup, migrate, validate, graph export, pages,
  505. captures, rebuilds, compatibility actions, and advanced updates.
  506. The stable agent-facing loop is documented at
  507. [Link Memory Contract](https://gowtham0992.github.io/link/memory-contract.html):
  508. readiness first, bounded recall, explicit memory writes, audit tools, and
  509. sharing semantics.
  510. Use `review_after` for time-sensitive preferences or decisions. When that date
  511. arrives, the memory reappears in Link's review inbox so an agent can ask the
  512. user to confirm, update, archive, or forget it instead of trusting stale context.
  513. Use `expires_at` for temporary context that should automatically leave default
  514. recall after a date; Link keeps the Markdown page inspectable and asks the user
  515. to update, archive, or delete it.
  516. Use `visibility` to separate where a memory applies from who should see it:
  517. `private` stays personal, `project` is intended for a project workspace, and
  518. `team` means the user explicitly approved sharing it with a team.
  519. For team handoff or security review, `lnk compliance-export --output audit.json`
  520. writes a redacted JSON packet with readiness, validation, memory review status,
  521. operation markers, and recent audit log entries. Raw source contents and memory
  522. bodies are not included.
  523. For day-to-day auditability, `lnk memory-log ~/link` shows what Link recently
  524. remembered, updated, reviewed, archived, restored, forgot, or accepted from raw
  525. captures.
  526. For recovery, `lnk backup ~/link` creates a local archive and `lnk
  527. restore-backup <archive> ~/link` previews what would be restored. Passing
  528. `--confirm` replaces local files after creating a safety backup when possible;
  529. `raw/` is still excluded unless `--include-raw` is explicit. If a multi-file
  530. write is interrupted, `lnk operations ~/link` shows the marker and any rollback
  531. snapshot; `lnk operations ~/link --recover <marker> --confirm` restores the
  532. snapshot after you review it.
  533. For local proof of value, `lnk wins ~/link` shows reusable memories, reviewed
  534. memory, provenance, project continuity, freshness guardrails, and copyable
  535. prompts without tracking user behavior.
  536. For Git-backed team memory, `lnk team-sync ~/link` checks whether the workspace
  537. is ready to share reviewed `wiki/` pages while keeping `raw/`, caches, backups,
  538. local MCP Python markers, and `wiki/log.md` private by default. The audit log is
  539. local because it has a single-machine hash chain; merging multiple users' logs
  540. would create false tamper alarms. Team sync also blocks "ready" status when the
  541. memory inbox is not clear or active `visibility: private` memories would be
  542. included by a broad `git add wiki`.
  543. ```bash
  544. lnk team-sync ~/link --remote git@example.com:team/link-memory.git
  545. ```
  546. For a teammate, reviewer, or another agent, `lnk share` resolves a page,
  547. memory, title, alias, or search phrase into a local viewer URL:
  548. ```bash
  549. lnk share "Prefer local memory" ~/link
  550. ```
  551. For a static, read-only review packet, `lnk snapshot` exports rendered wiki
  552. HTML without `raw/`, captures, operation markers, live MCP state, or memory pages
  553. by default. `--include-memories` exports only non-private memories; use
  554. `--include-private-memories` only for a personal archive or an explicitly
  555. approved review. It blocks export if wiki pages contain secret-looking values
  556. unless you explicitly override it.
  557. ```bash
  558. lnk snapshot ~/link --output link-snapshot
  559. lnk snapshot ~/link --output link-snapshot --include-memories --force
  560. lnk snapshot ~/link --output personal-snapshot --include-memories --include-private-memories --force
  561. ```
  562. ## Agent Contract
  563. For MCP clients, agents should use Link in this order:
  564. 1. `status` to check readiness and safe next actions.
  565. 2. `recall` with an empty query once at the first substantive turn of a session.
  566. 3. `recall(query, budget="micro"|"small")` before broad file reads or asking the user to repeat durable context.
  567. 4. `ingest` before touching raw sources and after source edits for validation/rebuild checks.
  568. 5. `remember` only when the user explicitly asks Link to remember something or approves a proposed memory.
  569. 6. `review` for memory inbox, profile, audit, log, explain, archive, restore, and forget workflows.
  570. 7. `admin` for backup, migration, graph export, captures, rebuilds, compatibility actions, and advanced maintenance.
  571. Full MCP tool list: [MCP setup](https://gowtham0992.github.io/link/mcp.html).
  572. ## Privacy And Safety
  573. Link itself is local-first:
  574. - No telemetry in the installed CLI, MCP server, local web UI, or wiki runtime.
  575. - No hosted backend.
  576. - No external API calls from `serve.py` or `link-mcp`.
  577. - Raw sources and generated wiki pages are ignored by git by default.
  578. - `lnk backup` excludes `raw/` unless you explicitly pass `--include-raw`.
  579. - Secret-looking API keys, provider tokens, JWTs, registry credentials, and
  580. private key blocks are detected in raw sources, captures, and release hygiene
  581. checks. `lnk validate` and `lnk doctor` also fail if secret-looking values
  582. are found inside wiki pages before they can be served through the local UI or
  583. returned through agent context.
  584. - Optional semantic recall stays local: models load offline-only at recall
  585. time (only the explicit `lnk semantic --setup` may fetch a model, once), and
  586. embeddings live in plain JSON under `.link-cache/`.
  587. - Automatic session hooks store proposal-only notes; transcript extraction
  588. skips tool calls and outputs, and no durable memory is written without review.
  589. - The local web server binds to `127.0.0.1` and is not meant to be exposed to
  590. the internet without additional auth.
  591. Before sharing a repo, demo, or wiki:
  592. ```bash
  593. python3 link.py doctor
  594. python3 link.py validate
  595. python3 scripts/check_release_hygiene.py
  596. ```
  597. More detail: [Security guide](https://gowtham0992.github.io/link/security.html).
  598. ## Documentation
  599. | Need | Go here |
  600. |------|---------|
  601. | Run Link for the first time | [First 10 minutes](https://gowtham0992.github.io/link/getting-started.html) |
  602. | "Does Link read my conversations?" | [The three questions everyone asks](https://gowtham0992.github.io/link/getting-started.html#faq) |
  603. | Decide whether Link fits | [Why Link?](https://gowtham0992.github.io/link/why-link.html) |
  604. | Use the local viewer | [Web UI](https://gowtham0992.github.io/link/ui.html) |
  605. | Understand raw/wiki/memory | [Concepts](https://gowtham0992.github.io/link/concepts.html) |
  606. | Configure MCP | [MCP setup](https://gowtham0992.github.io/link/mcp.html) |
  607. | Find a command | [CLI reference](https://gowtham0992.github.io/link/cli.html) |
  608. | Use Link without MCP setup | [Official skills](https://gowtham0992.github.io/link/skills.html) |
  609. | Use local HTTP endpoints | [HTTP API](https://gowtham0992.github.io/link/api.html) |
  610. | Review security boundaries | [Security model](https://gowtham0992.github.io/link/security.html) |
  611. | Check scale limits and measure your wiki | [Link Scale](https://gowtham0992.github.io/link/scale.html) |
  612. | Evaluate Link for a small team | [Team security review](https://gowtham0992.github.io/link/team-security.html) |
  613. | Fix setup issues | [Troubleshooting](https://gowtham0992.github.io/link/troubleshooting.html) |
  614. ## Contributing
  615. Contributions should come through pull requests targeting `main`. The `develop`
  616. branch is a maintainer integration branch for larger release work before it is
  617. proposed to `main`.
  618. Before opening a PR:
  619. ```bash
  620. python3 -m ruff check .
  621. python3 -m pytest tests
  622. python3 scripts/check_release_hygiene.py
  623. python3 scripts/check_runtime_duplication.py
  624. python3 scripts/check_tool_contract.py
  625. git diff --check
  626. ```
  627. Full contributor guide: [Contributing](https://gowtham0992.github.io/link/contributing.html).
  628. Do not include personal wiki data, raw sources, registry tokens, `.env` files, or
  629. local MCP credentials in a PR.
  630. If Link helps your agents remember better, [star it on GitHub](https://github.com/gowtham0992/link)
  631. so more people can find it.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.