diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 35456df..f0ec202 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,8 +81,11 @@ jobs: - name: Install MCP package for verification run: python -m pip install ./mcp_package - - name: Run portability tests - run: python -m unittest tests.test_mcp_verify_core tests.test_web_http_core tests.test_release_hygiene tests.test_cli_parser_core tests.test_cli_runtime_core + - name: Install test runner + run: python -m pip install "pytest>=8,<10" + + - name: Run broad Windows tests + run: python -m pytest tests -q --ignore=tests/test_installers.py --ignore=tests/test_serve.py --ignore=tests/test_large_wiki_smoke.py - name: Demo value-loop smoke test shell: pwsh @@ -112,6 +115,13 @@ jobs: - name: Check shell syntax run: bash -n integrations/*/install.sh integrations/*/uninstall.sh integrations/_shared/*.sh + - name: Check PowerShell syntax + shell: pwsh + run: | + Get-ChildItem integrations -Recurse -Include *.ps1 | ForEach-Object { + [scriptblock]::Create((Get-Content -Raw $_.FullName)) | Out-Null + } + release-hygiene: runs-on: ubuntu-latest steps: diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e89346..873ef0c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,45 @@ Release sections use `MAJOR.MINOR.PATCH` versions that match `link-mcp` on PyPI ## [Unreleased] +## [1.4.0] - 2026-06-14 + +### Added + +- Added official CLI skills under `skills/` so agents can lazy-load Link workflows without MCP setup. +- Added `lnk try` as a one-command demo proof loop that creates the demo, checks readiness, runs query/brief examples, and prints first agent prompts. +- Added `lnk connect ` to preview or write MCP client config for Codex, Kiro, Claude Code, Cursor, Antigravity, VS Code, and Copilot. +- Added Windows PowerShell installers for Codex, Kiro, Claude Code, Cursor, Antigravity, VS Code, and Copilot. +- Added optional `review_after` dates for durable memories so time-sensitive context can automatically return to the memory inbox for re-checking. +- Added optional `expires_at` dates for durable memories so temporary context automatically leaves default recall after expiry. +- Added `lnk import-obsidian ` to copy Obsidian Markdown notes into `raw/obsidian/` with secret scanning before the normal ingest workflow. +- Added `lnk compliance-export` for redacted readiness, validation, memory-review, operation, and log exports for team or security review. +- Added `lnk restore-backup` to preview and confirm local backup restores with unsafe-tar checks, raw restore opt-in, and pre-restore safety backups. +- Added `lnk team-sync` to print a safe Git sharing plan for reviewed team memory without pushing private raw sources automatically. +- Added `lnk share ` to print a local viewer permalink and agent prompt for a specific Link page. +- Added `lnk snapshot` to export a static, read-only HTML snapshot for demos or reviews while excluding raw sources, captures, live state, and memory pages by default. +- Added memory `visibility` metadata (`private`, `project`, or `team`) so team sharing can rely on explicit user intent instead of inferring privacy from scope alone. +- Added `lnk set-memory-visibility` and MCP `set_memory_visibility` so existing memories can move between private, project, and team sharing intent after explicit user approval. +- Added `lnk memory-log`, MCP `memory_log`, `/memory-log`, and `/api/memory-log` for recent memory lifecycle changes without exposing raw source or memory bodies. +- Added privacy-safe memory-log change summaries so review, status, and visibility transitions are visible without exposing memory bodies. +- Added `lnk wins`, MCP `memory_wins`, `/wins`, and `/api/wins` for local, non-telemetry proof signals about what Link memory is carrying. +- Added a team security review docs page covering local deployment, data boundaries, memory approval gates, Git sharing, audit exports, and current limits. +- Added a memory contract docs page that explains the stable MCP agent loop, tool groups, write rules, budget behavior, and sharing semantics. +- Added an integration maintainer checklist covering installer invariants, new-agent steps, PowerShell parity, and validation commands. +- Added a scale model docs page covering bounded defaults, benchmark/health checks, large-wiki habits, and current local limits. +- Added `python -m link_mcp --version` so MCP package installs can be verified before a wiki exists. +- Added an Obsidian guide for opening Link's Markdown wiki as a vault and rebuilding indexes after manual edits. +- Added validation and doctor failures for secret-looking values already present in wiki pages so local UI and MCP context do not quietly serve manually introduced secrets. + +### Changed + +- Broadened local secret detection for common modern provider tokens and credentials before capture, ingest, Obsidian import, and doctor scans. +- Changed the installed CLI command from `link` to `lnk` to avoid the POSIX/macOS `link` utility collision while preserving source-checkout `python3 link.py ...` usage. +- Tightened `lnk team-sync` readiness so unreviewed memories or active `visibility: private` memories block "ready" status before Git sharing. +- Tightened `lnk snapshot --include-memories` so private memories stay excluded unless `--include-private-memories` is explicitly passed. +- Broadened Windows CI from a small portability subset to most non-installer/non-server tests. +- Clarified that the Homebrew formula lives in the separate `gowtham0992/homebrew-link` tap. +- Tightened security reporting guidance to prefer private maintainer contact before public GitHub issues. + ## [1.3.0] - 2026-05-22 ### Added diff --git a/LINK.md b/LINK.md index e2f6106..8cbeed5 100644 --- a/LINK.md +++ b/LINK.md @@ -170,6 +170,7 @@ type: memory title: "Short Memory Title" memory_type: preference | decision | project | fact | note scope: user | project | global +visibility: private | project | team project: "optional-project-slug" status: active | stale | archived date_captured: "2026-04-09T14:30:00Z" @@ -178,6 +179,7 @@ update_count: 0 source: "manual | conversation | mcp | raw/source.md" last_update_source: "" review_status: pending | reviewed | needs_update +review_after: "optional YYYY-MM-DD date for scheduled re-check" tags: [memory, relevant-tag] --- @@ -287,6 +289,7 @@ Rules: - Keep memories specific and actionable. "User likes quality" is too vague; "User prefers release/* branches over codex/* branches" is useful. - Use `memory_type: preference` for user preferences, `decision` for choices made, `project` for project context, `fact` for stable facts, and `note` for everything else. - Use `scope: user` for broad personal preferences, `project` for the current project, and `global` for agent-wide principles. +- Use `visibility: private` for personal memory, `project` for project-team sharing, and `team` only when the human explicitly wants the memory shared across a team workspace. If omitted, Link treats user/global memories as private and project memories as project-visible. - For `scope: project`, include a project key when you know it. `link.py` infers this from repo-local installs; otherwise pass `--project ` or MCP `project`. - At the start of a session or substantial task, run `python3 link.py brief "" .` or MCP `memory_brief` when available. Treat this as the default way to prime yourself with local memory, review warnings, and saved raw capture status. - For long chat/session notes, prefer `python3 link.py capture-session "" .` or MCP `capture_session`; it stores the raw note locally and returns proposal-only memory candidates. If you do not need to keep the raw note, run `python3 link.py propose-memories "" .` or MCP `propose_memories` instead. Do not write proposals until the human confirms. diff --git a/README.md b/README.md index aa450b0..ae5c931 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,54 @@

- Link + Link

-# Link +

Link

-**Local, source-backed memory for LLM agents.** +

Local memory for AI agents.

-Link gives Codex, Claude, Cursor, Kiro, VS Code, Copilot, and other MCP clients -the same durable memory about you and your work. It stays on your machine as -plain Markdown, with sources, backlinks, graph context, review state, and an -audit trail you can inspect. +

+ Link gives Codex, Claude, Cursor, Kiro, VS Code, Copilot, Antigravity, and + other local agents the same source-backed memory, stored locally as Markdown. +

-It 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. +

+ Website · + Quick start · + MCP setup · + Skills · + CLI · + MCP Registry · + PyPI · + Homebrew +

+ +

+ GitHub stars + CI + MCP Registry + PyPI +

+ +## 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. -[![GitHub](https://img.shields.io/github/stars/gowtham0992/link?style=flat)](https://github.com/gowtham0992/link) -[![CI](https://github.com/gowtham0992/link/actions/workflows/ci.yml/badge.svg)](https://github.com/gowtham0992/link/actions/workflows/ci.yml) -[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.gowtham0992%2Flink-blue)](https://registry.modelcontextprotocol.io/?q=io.github.gowtham0992%2Flink) -[![PyPI](https://img.shields.io/pypi/v/link-mcp)](https://pypi.org/project/link-mcp/) +## How It Works -[Product site](https://gowtham0992.github.io/link/) · -[First 10 minutes](https://gowtham0992.github.io/link/getting-started.html) · -[Why Link?](https://gowtham0992.github.io/link/why-link.html) · -[Web UI](https://gowtham0992.github.io/link/ui.html) · -[MCP setup](https://gowtham0992.github.io/link/mcp.html) · -[CLI](https://gowtham0992.github.io/link/cli.html) · -[Security](SECURITY.md) · -[Changelog](CHANGELOG.md) +Link gives agents four simple moves: -## Why It Exists +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 @@ -43,6 +61,11 @@ into local memory agents can query. | 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 @@ -52,12 +75,14 @@ macOS with Homebrew: ```bash brew install gowtham0992/link/link -link demo -link next link-demo -link serve link-demo +lnk try +lnk serve link-demo ``` -Windows or source checkout: +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 @@ -67,7 +92,7 @@ py link.py next link-demo py link.py serve link-demo ``` -Or from source: +Source checkout on macOS/Linux: ```bash git clone https://github.com/gowtham0992/link.git @@ -77,6 +102,13 @@ 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 @@ -89,15 +121,15 @@ 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 `link welcome link-demo`. +For the shortest guided proof path, run `lnk welcome link-demo`. Try the value loop: ```bash -link query "why does Link help agents?" link-demo --budget small -link brief "working on agent memory" link-demo -link benchmark "agent memory" link-demo -link health link-demo +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, @@ -131,12 +163,21 @@ 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. -## Three Ways To Use Link +## 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. +
@@ -157,6 +198,19 @@ local Markdown wiki.
+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: @@ -175,9 +229,17 @@ 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. -The shell installers are intended for macOS/Linux-style agent config paths. -On Windows, use the source commands above plus the MCP-only config below until -your agent has a Windows-specific installer. +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: @@ -190,11 +252,23 @@ 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 +``` +
MCP-only install ```bash python3 -m pip install --upgrade link-mcp +python3 -m link_mcp --version ``` ```json @@ -219,17 +293,28 @@ python3 -m venv ~/.link-mcp-venv Full setup: [MCP guide](https://gowtham0992.github.io/link/mcp.html).
-## How Link Works +Obsidian users can import an existing vault into `raw/` for agent ingest, or +open `~/link/wiki` directly as a vault for editing Link pages: + +```bash +lnk init ~/link +lnk import-obsidian ~/Documents/ObsidianVault ~/link +``` + +See the [Obsidian guide](https://gowtham0992.github.io/link/obsidian.html) for +the import, edit, and validation loop. + +## Storage Model -Link separates source-backed knowledge from durable agent memory: +Under the hood, Link separates source-backed knowledge from durable agent memory: 1. Drop raw notes, transcripts, articles, and project context into `raw/`. 2. Agents compile those sources into inspectable pages under `wiki/`. 3. Explicit "remember" requests become reviewable memory pages. -4. Queries retrieve compact MCP context from both the wiki and memory layer. +4. Queries retrieve compact agent context from both the wiki and memory layer.

- Link architecture: raw sources become wiki knowledge, explicit remembers become reviewed memory, and agents retrieve compact MCP context + Link architecture: raw sources become wiki knowledge, explicit remembers become reviewed memory, and agents retrieve compact context

The storage model is plain and inspectable: @@ -238,14 +323,17 @@ The storage model is plain and inspectable: |-------|------------------| | `raw/` | Original notes, transcripts, articles, PDFs, screenshots, and project files. | | `wiki/` | Source-backed pages, concepts, entities, explorations, comparisons, and memories. | -| MCP tools | Compact packets agents can use without dumping the whole wiki into context. | +| Agent interfaces | CLI, skills, MCP, and local viewer paths that avoid dumping the whole wiki into context. | -If a raw file was already ingested and later edited, `link ingest-status` marks it +If a raw file was already ingested and later edited, `lnk ingest-status` marks it as stale and tells your agent to refresh the existing source page instead of creating a duplicate. ## What Agents Get +When an agent uses Link through MCP, these are the stable tools it receives. +CLI and skill workflows call the same core behavior through `lnk`. + - `query_link`: an answer-ready packet with relevant memories, pages, graph neighborhood, reasons for selection, budget limits, and follow-up actions. - `memory_brief`: a compact pre-work brief with user/project preferences, @@ -253,13 +341,83 @@ creating a duplicate. - `ingest_status`: exact next steps for raw files, including source safety, stale ingest detection, validation, and memory proposal guidance. - `remember_memory`: durable local memory with duplicate/conflict checks, - review state, provenance, and audit logging. + `visibility` sharing intent, review state, optional `review_after` re-check + dates, optional `expires_at` expiry dates, provenance, and audit logging. +- `set_memory_visibility`: explicit post-review sharing changes between + `private`, `project`, and `team` visibility without editing Markdown by hand. - `explain_memory`: why a memory exists, what it links to, whether it is ready for recall, and what needs review. +- `memory_log`: recent memory lifecycle changes from `wiki/log.md`, without + raw source or memory bodies. +- `memory_wins`: local proof signals for what Link memory is carrying, based + on wiki metadata rather than telemetry. + +The stable agent-facing loop is documented at +[Link Memory Contract](https://gowtham0992.github.io/link/memory-contract.html): +readiness first, bounded recall, explicit memory writes, audit tools, and +sharing semantics. + +Use `review_after` for time-sensitive preferences or decisions. When that date +arrives, the memory reappears in Link's review inbox so an agent can ask the +user to confirm, update, archive, or forget it instead of trusting stale context. +Use `expires_at` for temporary context that should automatically leave default +recall after a date; Link keeps the Markdown page inspectable and asks the user +to update, archive, or delete it. +Use `visibility` to separate where a memory applies from who should see it: +`private` stays personal, `project` is intended for a project workspace, and +`team` means the user explicitly approved sharing it with a team. + +For team handoff or security review, `lnk compliance-export --output audit.json` +writes a redacted JSON packet with readiness, validation, memory review status, +operation markers, and recent audit log entries. Raw source contents and memory +bodies are not included. + +For day-to-day auditability, `lnk memory-log ~/link` shows what Link recently +remembered, updated, reviewed, archived, restored, forgot, or accepted from raw +captures. + +For recovery, `lnk backup ~/link` creates a local archive and `lnk +restore-backup ~/link` previews what would be restored. Passing +`--confirm` replaces local files after creating a safety backup when possible; +`raw/` is still excluded unless `--include-raw` is explicit. + +For local proof of value, `lnk wins ~/link` shows reusable memories, reviewed +memory, provenance, project continuity, freshness guardrails, and copyable +prompts without tracking user behavior. + +For Git-backed team memory, `lnk team-sync ~/link` checks whether the workspace +is ready to share reviewed `wiki/` pages while keeping `raw/`, caches, backups, +and local MCP Python markers private by default. It also blocks "ready" status +when the memory inbox is not clear or active `visibility: private` memories +would be included by a broad `git add wiki`. + +```bash +lnk team-sync ~/link --remote git@example.com:team/link-memory.git +``` + +For a teammate, reviewer, or another agent, `lnk share` resolves a page, +memory, title, alias, or search phrase into a local viewer URL: + +```bash +lnk share "Prefer local memory" ~/link +``` + +For a static, read-only review packet, `lnk snapshot` exports rendered wiki +HTML without `raw/`, captures, operation markers, live MCP state, or memory pages +by default. `--include-memories` exports only non-private memories; use +`--include-private-memories` only for a personal archive or an explicitly +approved review. It blocks export if wiki pages contain secret-looking values +unless you explicitly override it. + +```bash +lnk snapshot ~/link --output link-snapshot +lnk snapshot ~/link --output link-snapshot --include-memories --force +lnk snapshot ~/link --output personal-snapshot --include-memories --include-private-memories --force +``` ## Agent Contract -Agents should use Link in this order: +For MCP clients, agents should use Link in this order: 1. `link_status` to check readiness and safe next actions. 2. `starter_prompts` when the user asks what to try first. @@ -280,9 +438,12 @@ Link itself is local-first: - No hosted backend. - No external API calls from `serve.py` or `link-mcp`. - Raw sources and generated wiki pages are ignored by git by default. -- `link backup` excludes `raw/` unless you explicitly pass `--include-raw`. -- Secret-looking values are detected in raw sources, captures, and release - hygiene checks. +- `lnk backup` excludes `raw/` unless you explicitly pass `--include-raw`. +- Secret-looking API keys, provider tokens, JWTs, registry credentials, and + private key blocks are detected in raw sources, captures, and release hygiene + checks. `lnk validate` and `lnk doctor` also fail if secret-looking values + are found inside wiki pages before they can be served through the local UI or + returned through agent context. - The local web server binds to `127.0.0.1` and is not meant to be exposed to the internet without additional auth. @@ -306,8 +467,10 @@ More detail: [Security guide](https://gowtham0992.github.io/link/security.html). | Understand raw/wiki/memory | [Concepts](https://gowtham0992.github.io/link/concepts.html) | | Configure MCP | [MCP setup](https://gowtham0992.github.io/link/mcp.html) | | Find a command | [CLI reference](https://gowtham0992.github.io/link/cli.html) | +| Use Link without MCP setup | [Official skills](https://gowtham0992.github.io/link/skills.html) | | Use local HTTP endpoints | [HTTP API](https://gowtham0992.github.io/link/api.html) | | Review security boundaries | [Security model](https://gowtham0992.github.io/link/security.html) | +| Evaluate Link for a small team | [Team security review](https://gowtham0992.github.io/link/team-security.html) | | Fix setup issues | [Troubleshooting](https://gowtham0992.github.io/link/troubleshooting.html) | ## Contributing diff --git a/SECURITY.md b/SECURITY.md index 1ed73fa..16afa86 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -49,6 +49,7 @@ working directory. ## Reporting vulnerabilities -Please report security issues through GitHub issues or private maintainer -contact channels. Avoid posting secrets, private wiki content, or raw source -files in public reports. +Please use a private maintainer contact channel for security issues first. Do +not post secrets, private wiki content, raw source files, or exploitable details +in public GitHub issues. If a public issue is the only available path, keep it +high level and ask for a private follow-up channel. diff --git a/docs/api.html b/docs/api.html index 9eb06ba..c00e689 100644 --- a/docs/api.html +++ b/docs/api.html @@ -21,10 +21,13 @@
Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -67,6 +70,8 @@

Read Endpoints

GET /api/memory-audit?project=slug GET /api/memory-profile?project=slug GET /api/memory-inbox?project=slug +GET /api/wins?project=slug +GET /api/memory-log?limit=50 GET /api/capture-inbox?project=slug GET /api/explain-memory?memory=name GET /api/query-link?q=query&budget=small|medium|large @@ -90,6 +95,7 @@

Write Endpoints

POST /api/rebuild-backlinks POST /api/rebuild-index

Web memory approval APIs intentionally do not honor duplicate/conflict override flags. If Link reports a duplicate or conflict, review the existing memory and use the CLI or MCP tool explicitly after deciding what should coexist.

+

POST /api/remember-memory accepts optional visibility, review_after, and expires_at fields for sharing intent, scheduled review, and temporary-memory expiry.

Large Wiki Endpoints

Agents and integrations should prefer bounded endpoints over full dumps:

diff --git a/docs/assets/site.css b/docs/assets/site.css index 41790b9..5c8fbe5 100644 --- a/docs/assets/site.css +++ b/docs/assets/site.css @@ -263,6 +263,7 @@ section:nth-child(2n), .feature, .panel { + min-width: 0; min-height: 198px; padding: 20px; border: 3px solid var(--border); @@ -289,6 +290,39 @@ section:nth-child(2n), margin-top: 34px; } +.proof-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 22px; + margin-top: 34px; +} + +.proof-column { + min-width: 0; + padding: 22px; + border: 3px solid var(--border); + background: var(--paper-2); + box-shadow: var(--shadow); +} + +.proof-column.before { background: #ffe1dc; } +.proof-column.after { background: #dff8ef; } + +.proof-column ol { + margin: 14px 0 20px; + padding-left: 22px; +} + +.proof-column li { + margin: 7px 0; + font-weight: 650; +} + +.proof-column pre { + box-shadow: none; + font-size: 13px; +} + .screenshot-row { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); @@ -304,6 +338,7 @@ section:nth-child(2n), } .media-card { + min-width: 0; padding: 12px; border: 3px solid var(--border); background: var(--paper-2); @@ -337,6 +372,7 @@ section:nth-child(2n), } .screenshot-card { + min-width: 0; margin: 0; padding: 12px; border: 3px solid var(--border); @@ -346,6 +382,7 @@ section:nth-child(2n), } .architecture-card { + min-width: 0; margin: 34px 0 0; padding: 12px; border: 3px solid var(--border); @@ -386,6 +423,7 @@ figcaption { pre { position: relative; + max-width: 100%; overflow-x: auto; margin: 0; padding: 20px; @@ -571,13 +609,14 @@ footer a { .grid, .grid.two-up, .flow, + .proof-grid, .screenshot-row, .media-grid, .compare, .doc-table, .choice-table, .choice-table div { - grid-template-columns: 1fr; + grid-template-columns: minmax(0, 1fr); } .toc { diff --git a/docs/cli.html b/docs/cli.html index 87c5a67..108ed75 100644 --- a/docs/cli.html +++ b/docs/cli.html @@ -21,10 +21,13 @@
Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -36,7 +39,7 @@
Command reference

Local commands for daily memory work.

-

Install the CLI with brew install gowtham0992/link/link on macOS, or use link <command> after a global agent installer run. From a source checkout, use python3 link.py <command> on macOS/Linux or py link.py <command> on Windows.

+

Install the CLI with brew install gowtham0992/link/link on macOS, or use lnk <command> after a global agent installer run. Link uses lnk because link is already a POSIX/macOS system utility. From a source checkout, use python3 link.py <command> on macOS/Linux or py link.py <command> on Windows.

@@ -57,96 +60,123 @@

CLI Tour

Animated Link CLI walkthrough
Status, query, brief, and benchmark are the core terminal loop.
+

The CLI is independent of the web viewer. Use lnk query, lnk brief, lnk health, and maintenance commands even when lnk serve is not running. Agents that support lazy-loaded instructions can also use the official Link skills instead of MCP setup.

+

Use lnk try when you want the shortest proof loop: demo creation, readiness, query proof, brief proof, viewer command, and first agent prompts in one command.

Daily Loop

- 
link serve
-link welcome
-link next
-link health
-link ingest-status
-link remember "User prefers feature branches for Link work." --type preference --scope project --project link
-link brief "working on Link release" --project link
-link query "what should I know before changing the MCP tools?" --budget small --project link
-link validate
+ 
lnk serve
+lnk welcome
+lnk next
+lnk health
+lnk ingest-status
+lnk remember "User prefers feature branches for Link work." --type preference --scope project --project link --visibility project --review-after 2026-08-01
+lnk remember "Temporary launch branch is release/one-off." --type project --project link --expires-at 2026-09-01
+lnk share "Prefer local memory"
+lnk snapshot ~/link --output link-snapshot
+lnk brief "working on Link release" --project link
+lnk query "what should I know before changing the MCP tools?" --budget small --project link
+lnk validate

Memory Commands

-

link remember

Save a local agent memory. Strong duplicates and likely conflicts are refused unless explicitly allowed.

-

link recall

Search local memories with recall readiness and project-aware filtering.

-

link explain-memory

Show provenance, lifecycle, graph links, review issues, and recall readiness.

-

link update-memory

Merge new text into an existing memory and reset review state.

-

link archive-memory

Reversibly hide a stale or wrong memory from default recall.

-

link forget-memory

Permanently delete a memory after explicit confirmation.

+

lnk remember

Save a local agent memory. Strong duplicates and likely conflicts are refused unless explicitly allowed.

+

lnk recall

Search local memories with recall readiness and project-aware filtering.

+

lnk explain-memory

Show provenance, lifecycle, graph links, review issues, and recall readiness.

+

lnk update-memory

Merge new text into an existing memory and reset review state.

+

lnk archive-memory

Reversibly hide a stale or wrong memory from default recall.

+

lnk forget-memory

Permanently delete a memory after explicit confirmation.

Capture Workflow

Use captures for longer chat notes or session summaries that should be reviewed before becoming durable memory.

- 
link capture-session session-notes.md --project link
-link capture-inbox --project link
-link accept-capture raw/memory-captures/<capture>.md --index 1
-link redact-capture raw/memory-captures/<capture>.md
-link delete-capture raw/memory-captures/<capture>.md --confirm
+ 
lnk capture-session session-notes.md --project link
+lnk capture-inbox --project link
+lnk accept-capture raw/memory-captures/<capture>.md --index 1
+lnk redact-capture raw/memory-captures/<capture>.md
+lnk delete-capture raw/memory-captures/<capture>.md --confirm

Maintenance

- 
link backup
-link doctor --fix
-link health
-link status --validate
-link memory-audit
-link operations
-link benchmark "agent memory"
-link rebuild-index
-link rebuild-backlinks
-link validate
-link verify-mcp
-

Use link backup before broad repair work. Use link benchmark when a wiki starts to feel slow. link status --validate and link benchmark both show persistent-cache reuse so you can tell whether Link is rereading every page or reusing unchanged records.

-

From a source checkout, use the synthetic large-wiki smoke when you want local scale evidence without touching your real wiki. The script prints the exact link serve command and graph URL for the generated fixture.

+ 
lnk backup
+lnk doctor --fix
+lnk health
+lnk status --validate
+lnk memory-audit
+lnk compliance-export --output link-audit.json
+lnk team-sync ~/link
+lnk snapshot ~/link --output link-snapshot
+lnk operations
+lnk benchmark "agent memory"
+lnk rebuild-index
+lnk rebuild-backlinks
+lnk validate
+lnk verify-mcp
+

Use lnk backup before broad repair work. Use lnk benchmark when a wiki starts to feel slow. lnk status --validate and lnk benchmark both show persistent-cache reuse so you can tell whether Link is rereading every page or reusing unchanged records.

+

Use lnk team-sync before sharing Link through Git. It is read-only: it checks Git state, verifies that raw/ is protected, checks whether review or visibility: private memories would make sharing unsafe, and prints paste-safe setup/sync commands without pushing private source material for you.

+

Use lnk snapshot when you need a static, read-only HTML export for a teammate, maintainer, security reviewer, or demo. It excludes raw/, captures, local operation state, and memory pages by default. With --include-memories, it still excludes visibility: private memories unless --include-private-memories is explicitly passed.

+

Use lnk connect <agent> when an agent already has Link instructions but still needs MCP wiring. It previews the config before writing.

+ 
lnk connect codex ~/link
+lnk connect codex ~/link --write
+lnk connect kiro ~/link --write
+lnk verify-mcp ~/link
+

From a source checkout, use the synthetic large-wiki smoke when you want local scale evidence without touching your real wiki. The script prints the exact lnk serve command and graph URL for the generated fixture.

python3 scripts/smoke_large_wiki.py --pages 10000

All Commands

- 
link --version
-link version
-link init [dir]
-link serve [dir] [--port 3000]
-link welcome [dir] [--project slug]
-link prompts [dir] [--project slug]
-link next [dir] [--project slug]
-link health [dir] [--json]
-link status [--validate]
-link operations [--limit 20]
-link backup [--label name] [--include-raw]
-link ingest-status
-link remember "text" [--project slug]
-link propose-memories <file-or-text> [--project slug]
-link capture-session <file-or-text> [--project slug]
-link capture-inbox [--project slug]
-link accept-capture <capture> [--index N]
-link redact-capture <capture>
-link delete-capture <capture> --confirm
-link query "task" [--budget small|medium|large] [--project slug]
-link graph-summary ["topic"] [--limit 40] [--depth 1]
-link benchmark ["query"] [--budget small|medium|large] [--project slug]
-link brief "task" [--project slug]
-link memory-audit [--project slug]
-link recall "query" [--project slug]
-link profile [--project slug]
-link memory-inbox [--project slug]
-link review-memory <name>
-link explain-memory <name>
-link update-memory <name> "text" [--project slug]
-link archive-memory <name>
-link restore-memory <name>
-link forget-memory <name> --confirm
-link doctor
-link doctor --fix
-link migrate
-link validate [--strict]
-link rebuild-index
-link rebuild-backlinks
-link verify-mcp [--json]
+        
lnk --version
+lnk version
+lnk init [dir]
+lnk serve [dir] [--port 3000]
+lnk try [dir] [--force] [--serve] [--port 3000]
+lnk welcome [dir] [--project slug]
+lnk prompts [dir] [--project slug]
+lnk next [dir] [--project slug]
+lnk health [dir] [--json]
+lnk status [--validate]
+lnk operations [--limit 20]
+lnk backup [--label name] [--include-raw]
+lnk compliance-export [dir] [--output audit.json] [--project slug]
+lnk team-sync [dir] [--remote git-url]
+lnk share <page-or-memory> [dir] [--port 3000]
+lnk snapshot [dir] [--output link-snapshot] [--include-memories] [--include-private-memories] [--force]
+lnk ingest-status
+lnk import-obsidian <vault> [dir] [--dry-run] [--overwrite]
+lnk remember "text" [--project slug] [--visibility private|project|team] [--review-after YYYY-MM-DD] [--expires-at YYYY-MM-DD]
+lnk propose-memories <file-or-text> [--project slug]
+lnk capture-session <file-or-text> [--project slug]
+lnk capture-inbox [--project slug]
+lnk accept-capture <capture> [--index N] [--visibility private|project|team]
+lnk redact-capture <capture>
+lnk delete-capture <capture> --confirm
+lnk query "task" [--budget small|medium|large] [--project slug]
+lnk graph-summary ["topic"] [--limit 40] [--depth 1]
+lnk benchmark ["query"] [--budget small|medium|large] [--project slug]
+lnk brief "task" [--project slug]
+lnk memory-audit [--project slug]
+lnk recall "query" [--project slug]
+lnk profile [--project slug]
+lnk wins [--project slug]
+lnk memory-inbox [--project slug]
+lnk memory-log [--limit N]
+lnk review-memory <name>
+lnk explain-memory <name>
+lnk update-memory <name> "text" [--project slug]
+lnk set-memory-visibility <name> private|project|team
+lnk archive-memory <name>
+lnk restore-memory <name>
+lnk forget-memory <name> --confirm
+lnk doctor
+lnk doctor --fix
+lnk migrate
+lnk validate [--strict]
+lnk rebuild-index
+lnk rebuild-backlinks
+lnk verify-mcp [--json]
+lnk connect <agent> [dir] [--write] [--config path] [--python python]
+lnk backup [--list] [--include-raw]
+lnk restore-backup <backup.tar.gz> [--include-raw] --confirm
 python3 link.py demo
 python3 link.py query-link "task" [dir]

-        
query-link is kept as an internal/backward-compatible alias. Prefer link query in user-facing docs.

+        
query-link is kept as an internal/backward-compatible alias. Prefer lnk query in user-facing docs.
diff --git a/docs/concepts.html b/docs/concepts.html index 9fc1520..f2c33ca 100644 --- a/docs/concepts.html +++ b/docs/concepts.html @@ -21,10 +21,13 @@
Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -58,8 +61,12 @@

Storage Layers

-> direct memories -> review/update/archive
Link architecture: raw sources, structured wiki, reviewed memory, and MCP retrieval -
The wiki is the storage layer. Reviewed memory and MCP context are the product surface agents use.
+
The wiki is the storage layer. Reviewed memory and compact context are the product surfaces agents use.
+
+ One wiki, three independent surfaces + The web UI, CLI, official skills, and MCP server are separate ways to use the same local files. Closing the viewer does not stop CLI commands, skills, or MCP recall. +
Public repo versus local memory Link deliberately keeps generated raw/, wiki/, and link-demo/ content out of git. The tracked root wiki is scaffolding; python3 link.py demo creates the product-story demo wiki. @@ -70,7 +77,7 @@

Storage Layers

wiki/memories/Preferences, decisions, project facts, and user context.
indexesBacklinks, page index, local cache, token index, and optional SQLite FTS.
-

Markdown remains the source of truth. Derived indexes can be rebuilt. Agents maintain the files, but the files stay inspectable in git, Obsidian, or any editor.

+

Markdown remains the source of truth. Derived indexes can be rebuilt. Agents maintain the files, but the files stay inspectable in git, Obsidian, or any editor.

Three User Moves

Link deliberately separates knowledge from memory:

@@ -80,11 +87,13 @@

Three User Moves

Raw files do not silently personalize future agents. Ingest creates source-backed wiki knowledge. Explicit remember creates durable user or project memory.

Memory Lifecycle

-

A memory is a Markdown page with status, scope, source, review state, graph links, and local log entries. It can be proposed, remembered, reviewed, updated, archived, restored, explained, or forgotten.

+

A memory is a Markdown page with status, scope, visibility, source, review state, optional review_after and expires_at dates, graph links, and local log entries. It can be proposed, remembered, reviewed, updated, archived, restored, explained, or forgotten.

Propose

Generate candidate memories from chat notes or raw captures without writing durable memory.

Approve

Save only the memories the user explicitly wants agents to carry forward.

Explain

Show why a memory exists, whether it is recall-ready, and what graph links support it.

+

Re-check

Use review_after when a memory should come back to the inbox after a date instead of staying trusted forever.

+

Expire

Use expires_at for temporary context that should leave default recall after a date while staying inspectable.

Smart Query Packets

@@ -105,11 +114,11 @@

Graph Context

Scale Model

Link uses local caching, token indexes, bounded page APIs, bounded graph summaries, and optional in-memory SQLite FTS5 for fast search. If SQLite is unavailable, Link falls back to the token index.

- 
link benchmark "agent memory"
-link graph-summary "local memory" --limit 40 --depth 1
-link validate
-link rebuild-backlinks
-

Use link benchmark when a wiki starts to feel slow. It reports cache time, persistent-cache reuse, search, query, graph payloads, backend, and readiness recommendations.

+ 
lnk benchmark "agent memory"
+lnk graph-summary "local memory" --limit 40 --depth 1
+lnk validate
+lnk rebuild-backlinks
+

Use lnk benchmark when a wiki starts to feel slow. It reports cache time, persistent-cache reuse, search, query, graph payloads, backend, and readiness recommendations.

diff --git a/docs/contributing.html b/docs/contributing.html index 5057fa3..082402f 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -21,10 +21,13 @@
Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -49,6 +52,7 @@

Keep Link local, inspectable, and reliable.

PR description Project structure Design principles + Installer integrations

Branches

@@ -67,6 +71,7 @@

Before Opening A PR

python3 scripts/check_runtime_duplication.py python3 scripts/check_tool_contract.py bash -n integrations/*/install.sh integrations/*/uninstall.sh integrations/_shared/*.sh +pwsh -NoProfile -Command "Get-ChildItem integrations -Recurse -Include *.ps1 | ForEach-Object { [scriptblock]::Create((Get-Content -Raw $_.FullName)) | Out-Null }" 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 @@ -105,6 +110,9 @@

Design Principles

  • 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.
    • + +

    Installer Integrations

    +

    Agent installers are part of Link's first-use product surface. If a change touches Codex, Claude Code, Kiro, Cursor, Copilot, VS Code, Antigravity, MCP config writing, or PowerShell support, follow the maintainer checklist in integrations/README.md. The key rule is simple: installers should preserve existing user instructions, keep CLI/MCP independent from the web viewer, and update macOS/Linux plus Windows paths together.

    diff --git a/docs/getting-started.html b/docs/getting-started.html index ab664d5..0dc945a 100644 --- a/docs/getting-started.html +++ b/docs/getting-started.html @@ -21,10 +21,13 @@
    Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -36,7 +39,7 @@
    First 10 minutes

    Turn one local note into agent memory.

    -

    Start with the demo, add one real source, save one explicit memory, then ask an MCP-enabled agent to query Link.

    +

    Start with the demo, add one real source, save one explicit memory, then ask an agent to query Link through MCP, skills, or the CLI.

    @@ -56,9 +59,9 @@

    1. Run The Demo

    The demo is the fastest proof of value. It already has raw sources, wiki pages, memories, backlinks, and graph data.

    macOS with Homebrew:

    brew install gowtham0992/link/link
-link demo
-link next link-demo
-link serve link-demo
    +lnk try +lnk serve link-demo +

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

    Or from source:

    git clone https://github.com/gowtham0992/link.git
 cd link
@@ -71,16 +74,21 @@ 
    1. Run The Demo
    
 py link.py demo
 py link.py next link-demo
 py link.py serve link-demo
    +

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

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

    The demo includes one pending memory intentionally, so the review inbox and explain-memory workflow are visible. Run link review-memory prefer-local-personal-memory link-demo if you want memory audit to be fully clear.

    +
    + Viewer is optional + lnk serve is only for browsing Link in a local web UI. CLI commands, official skills, and MCP-enabled agents work without it because they read the same local wiki/ files directly. +
    +

    The demo includes one pending memory intentionally, so the review inbox and explain-memory workflow are visible. Run lnk review-memory prefer-local-personal-memory link-demo if you want memory audit to be fully clear.

    Open http://127.0.0.1:3000, then inspect /brief, /memory, /ingest, /graph, and /health. Open more for prompts, proposal review, audit, captures, profile, log, and all pages. Link accepts localhost too, but the numeric loopback address avoids slow IPv6 fallback in some Safari setups.

    - 
    link query "why does Link help agents?" link-demo --budget small
-link brief "working on agent memory" link-demo
-link benchmark "agent memory" link-demo
-link health link-demo
    + 
    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

    2. Install Link For Your Agent

    From the cloned checkout, run the installer for the agent you use. Re-running the same installer updates code and instructions without replacing existing wiki data.

    @@ -92,7 +100,14 @@

    2. Install Link For Your Agent

    bash integrations/vscode/install.sh bash integrations/antigravity/install.sh

    Use --project for a repo-local Link install. Project-scoped memory then stays separate from other project memory while still allowing broad user memory to be recalled.

    -

    The shell installers target macOS/Linux-style agent config paths. On Windows, run Link from source and use the MCP-only setup in the MCP guide until a Windows-specific installer exists.

    +

    On Windows PowerShell, use the matching install.ps1 script:

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

    3. Add One Source

    Open the local viewer and use ingest -> Add Raw Source, or write a first note directly:

    @@ -110,14 +125,14 @@

    3. Add One Source

    Raw notes stay local. The agent turns them into source-cited wiki pages. EOF

    Check pending work:

    - 
    link ingest-status
    + 
    lnk ingest-status
    Safety gate Link blocks normal ingest guidance when raw files contain secret-looking values or cannot be read safely. Redact or fix those local files first.
    Existing Link data - If you already have files in ~/link/raw/, link ingest-status may point to a different pending file first. If first-memory.md was already ingested and you overwrite it, Link marks that raw file as stale and asks the agent to refresh the existing source page. + If you already have files in ~/link/raw/, lnk ingest-status may point to a different pending file first. If first-memory.md was already ingested and you overwrite it, Link marks that raw file as stale and asks the agent to refresh the existing source page.

    4. Save One Direct Memory

    @@ -126,11 +141,11 @@

    4. Save One Direct Memory

    brief me from Link before we continue what does Link remember about local personal memory?

    Or use the CLI:

    - 
    link remember "I am testing Link as local personal memory for agents." --type preference --scope user --tags onboarding
-link brief "local personal memory"
-link recall "local personal memory"
-link profile
-link memory-audit
    + 
    lnk remember "I am testing Link as local personal memory for agents." --type preference --scope user --tags onboarding
+lnk brief "local personal memory"
+lnk recall "local personal memory"
+lnk profile
+lnk memory-audit

    5. Ask The Agent To Ingest

    In your agent chat, ask:

    @@ -139,14 +154,14 @@

    5. Ask The Agent To Ingest

    Return to /ingest after the agent finishes. Link shows which raw files are represented and gives follow-up prompts for proposals or retrieval checks.

    6. Verify The Loop

    - 
    link doctor --fix
-link health
-link ingest-status
-link validate
-link memory-audit
-link operations
-link verify-mcp
    -

    link verify-mcp should report Result: ready. Then ask your MCP-enabled agent:

    + 
    lnk doctor --fix
+lnk health
+lnk ingest-status
+lnk validate
+lnk memory-audit
+lnk operations
+lnk verify-mcp
    +

    lnk verify-mcp should report Result: ready when you use MCP. Then ask your agent:

    query Link for first Link memory

    If the answer comes from Link, local agent memory is working.

    diff --git a/docs/index.html b/docs/index.html index 64eaeed..3d325d6 100644 --- a/docs/index.html +++ b/docs/index.html @@ -21,10 +21,13 @@
    Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -36,13 +39,15 @@
    Local agent memory

    Link gives every agent the same memory.

    -

    Source-backed Markdown memory for Codex, Claude, Cursor, Kiro, VS Code, Copilot, and any MCP client. Local files. Inspectable sources. Budgeted context.

    +

    Source-backed Markdown memory for Codex, Claude, Cursor, Kiro, VS Code, Copilot, Antigravity, and local agents. Local files. Inspectable sources. Budgeted context.

    • raw/
    • wiki/
    • memories/
    • graph
      • +
    • CLI
    • MCP
      • +
    • skills
    Try Link @@ -61,10 +66,12 @@

    Not another notes app. A local memory layer agents can actually use.

    Personal memory

    Preferences, decisions, facts, and project context stay durable across agent sessions.

    Source-backed wiki

    Raw sources compile into Markdown pages with citations, backlinks, and reviewable provenance.

    -

    MCP-native recall

    One local memory works across MCP-capable tools through the same query, brief, graph, and memory lifecycle tools.

    +

    Agent-ready recall

    One local memory works across CLI, skills, MCP-capable tools, and the local viewer through the same query, brief, graph, and memory lifecycle paths.

    Budgeted context

    Smart query packets return the right memory, pages, graph neighborhood, and follow-up actions without flooding tokens.

    +

    Measured scale

    Health and benchmark commands show cache reuse, search backend, graph shape, and bounded payload behavior as a wiki grows.

    Private by default

    No hosted backend, no telemetry, no cloud lock-in. Your memory stays on disk as plain Markdown.

    Auditable lifecycle

    Capture, propose, approve, review, archive, restore, forget, and explain what Link remembers.

    +

    Obsidian-readable

    Open the same wiki/ folder in Obsidian when you want a richer Markdown editor or graph view.

    @@ -73,14 +80,46 @@

    Not another notes app. A local memory layer agents can actually use.

    How it works

    A local memory pipeline agents can trust.

    -

    Raw sources become structured wiki pages. Explicit remembers become reviewed memory. Agents retrieve compact MCP context packets instead of reading your whole folder.

    +

    Raw sources become structured wiki pages. Explicit remembers become reviewed memory. Agents retrieve compact context packets instead of reading your whole folder.

    - Link architecture: capture sources, structure wiki knowledge, review memory, and retrieve compact MCP context + Link architecture: capture sources, structure wiki knowledge, review memory, and retrieve compact context
    Link keeps the knowledge base plain and local while giving agents a predictable recall path.
    +
    +
    +

    Before and after

    +

    The useful moment is not storage. It is continuity.

    +

    Link is built for the daily handoff between sessions and agents: stop re-explaining the same context, start from a brief that has provenance.

    +
    +
    +

    Without Link

    +
      +
    1. Open a new agent session.
      2. +
    2. Explain your project, preferences, and recent decisions again.
      3. +
    3. Paste notes or ask the agent to scan a folder.
      4. +
    4. Lose the context when you switch tools.
      5. +
    + 
    User: we talked about this yesterday...
+Agent: I do not have that context.
    +
    +
    +

    With Link

    +
      +
    1. Ask: brief me from Link before we continue.
      2. +
    2. The agent gets reviewed memory plus source-backed wiki context.
      3. +
    3. Decisions can be remembered, reviewed, archived, or forgotten.
      4. +
    4. Another MCP agent can recall the same local memory.
      5. +
    + 
    User: brief me from Link before we continue
+Agent: Here is the relevant memory, sources, and next safe action.
    +
    +
    +
    +
    +
    @@ -92,31 +131,36 @@

    Run a finished memory wiki locally.

    Troubleshooting
    - 
    # macOS
+        
    # macOS/Homebrew proof loop
 brew install gowtham0992/link/link
-link demo
-link next link-demo
-link serve link-demo
+lnk demo
+lnk next link-demo
+lnk serve link-demo
+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
 
-# or from source
+# source checkout proof loop
 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
-
-# then try
-link query "why does Link help agents?" link-demo --budget small
-link brief "working on agent memory" link-demo
-link benchmark "agent memory" link-demo
    
+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
    -

    Three surfaces

    +

    Access paths

    Review it, script it, or let an agent call it.

    -

    The web UI, CLI, and MCP server all operate on the same local Markdown wiki. Read it like a local document, script it from a terminal, or let an agent query the same memory through MCP.

    +

    The web UI, CLI, official skills, and MCP server all operate on the same local Markdown wiki. Read it like a local document, script it from a terminal, lazy-load a skill, or let an MCP client query the same memory.

    +
    + No background web server required + lnk serve only starts the human web viewer. The CLI, skills, and MCP server read the same local files directly, so agents can query Link when the viewer is closed. +
    Animated Link web UI walkthrough @@ -179,7 +223,7 @@

    Agents get a small set of reliable moves.

    Read next

    Start small, then make it your agent memory.

    -

    The docs are arranged by user path: try the demo, understand the model, wire MCP, then use the CLI and maintenance tools when you need them.

    +

    The docs are arranged by user path: try the demo, understand the model, choose MCP or skills, then use the CLI and maintenance tools when you need them.

    First 10 minutes

    Run the demo, add one source, save one direct memory, and verify the loop.

    Why Link?

    Understand where Link fits versus notes apps, hosted memory APIs, agent runtimes, and graph memory systems.

    @@ -187,8 +231,10 @@

    Start small, then make it your agent memory.

    Concepts

    Understand raw sources, wiki pages, memories, graph indexes, and budgeted query packets.

    MCP setup

    Install the MCP server and teach local agents how to use Link reliably.

    CLI reference

    Every local command, grouped by daily workflow and maintenance jobs.

    +

    Official skills

    Use lazy-loadable CLI workflows when MCP setup is more than you need.

    HTTP API

    Local endpoints for status, query, memory, graph, validation, and web UI actions.

    Security model

    Local-first constraints, secret scanning, backup behavior, and HTTP safety boundaries.

    +

    Team security review

    Deployment patterns, audit exports, Git sharing, approval gates, and current limits for small teams.

    Contributing

    PR expectations, test gates, branch policy, and what not to include in public changes.

    Troubleshooting

    Fix MCP setup, blocked ingest, stale graph indexes, slow wikis, and Python packaging issues.

    diff --git a/docs/mcp.html b/docs/mcp.html index 7914fd7..085e575 100644 --- a/docs/mcp.html +++ b/docs/mcp.html @@ -21,10 +21,13 @@
    Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -57,6 +60,15 @@

    MCP Tour

    Animated Link MCP agent walkthrough
    Agents use natural prompts, then call Link tools for readiness, briefs, query packets, and reviewed memory writes.
    +
    + MCP does not need serve.py + The local web viewer is only for humans. MCP clients start python -m link_mcp --wiki ... over stdio and read the same Markdown wiki directly. +
    +
    + Prefer no MCP? + Use the official Link skills when an agent can run local CLI commands and you want a lazy-loaded workflow instead of MCP configuration. +
    +

    For agent builders, the stable read/write behavior is summarized in the Link memory contract.

    Agent Installers

    Use the installer for the agent you use most. Installers create or update ~/link, install link-mcp, write short agent instructions, and preserve existing wiki data.

    @@ -68,9 +80,26 @@

    Agent Installers

    bash integrations/vscode/install.sh bash integrations/antigravity/install.sh

    Use --project from a repo when memory should be project-scoped.

    +

    On Windows PowerShell, use .\integrations\AGENT\install.ps1 instead:

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

    If you already have agent instructions and only need the MCP config, use lnk connect. It previews the target file and config snippet first; add --write for an explicit update.

    + 
    lnk connect codex ~/link
+lnk connect codex ~/link --write
+lnk connect kiro ~/link --write
+lnk connect claude-code ~/link --write
+lnk connect cursor ~/link --write
+lnk connect antigravity ~/link --write
+lnk verify-mcp ~/link

    MCP Only

    - 
    python3 -m pip install --upgrade link-mcp
    + 
    python3 -m pip install --upgrade link-mcp
+python3 -m link_mcp --version
    {
   "mcpServers": {
     "link": {
@@ -88,8 +117,8 @@ 
    MCP Only
    
         
    {
   "mcpServers": {
     "link": {
-      "command": "/Users/YOU/.link-mcp-venv/bin/python",
-      "args": ["-m", "link_mcp", "--wiki", "/Users/YOU/link/wiki"]
+      "command": "C:\\Users\\YOU\\.link-mcp-venv\\Scripts\\python.exe",
+      "args": ["-m", "link_mcp", "--wiki", "C:\\Users\\YOU\\link\\wiki"]
     }
   }
 }
    
@@ -121,6 +150,8 @@ 
    MCP Tools
    
 memory_audit
 memory_profile
 memory_inbox
+memory_log
+memory_wins
 review_memory
 explain_memory
 search_wiki
@@ -133,6 +164,7 @@ 
    MCP Tools
    
 redact_capture
 delete_capture
 update_memory
+set_memory_visibility
 archive_memory
 restore_memory
 forget_memory
@@ -143,14 +175,14 @@ 
    MCP Tools
    
 get_graph
 rebuild_index
 rebuild_backlinks
    -

    Memory write tools return duplicate_candidates or conflict_candidates when review, update, or archive is safer than creating another memory page.

    +

    Memory write tools return duplicate_candidates or conflict_candidates when review, update, or archive is safer than creating another memory page. remember_memory also accepts optional visibility, review_after, and expires_at fields for sharing intent, scheduled re-checks, and temporary memories.

    Project-aware tools accept an optional project argument. When set, Link returns broad user/global memory plus memories for that project, while excluding memories from other explicit projects.

    Verify Setup

    - 
    link verify-mcp
-link health
-link next
    -

    link verify-mcp --json is useful when an agent or script should read structured issues and next actions.

    + 
    lnk verify-mcp
+lnk health
+lnk next
    +

    lnk verify-mcp --json is useful when an agent or script should read structured issues and next actions.

    Natural prompts to try

    is Link ready?

    diff --git a/docs/memory-contract.html b/docs/memory-contract.html new file mode 100644 index 0000000..d889b9e --- /dev/null +++ b/docs/memory-contract.html @@ -0,0 +1,135 @@ + + + + + + + Link - Memory Contract + + + + + + + + + + + + + +
    +
    + Agent memory contract +

    A predictable local memory interface for agents.

    +

    Link's MCP tools give agents one stable loop: check readiness, get starter prompts, retrieve compact context, write only approved memory, and audit what changed.

    +
    +
    + +
    +
    + +
    +

    Contract Promise

    +

    Link is not asking every agent to learn a new notes app. It gives agents a small, repeatable memory contract backed by local Markdown files.

    +
    +

    Readable storage

    Raw source notes live in raw/. Structured pages and durable memories live in wiki/.

    +

    Bounded recall

    Agents ask for a task-sized packet instead of dumping the whole wiki into context.

    +

    Reviewable writes

    Durable memory writes are explicit, duplicate-checked, conflict-checked, and logged.

    +

    Local trust

    The CLI, official skills, HTTP viewer, and MCP server read the same local files. serve.py is not required for recall.

    +
    + +

    Recommended Agent Loop

    +
      +
    1. Call link_status. If schema or validation needs attention, call the repair tool the payload suggests.
      2. +
    2. Call starter_prompts when a user asks what to try first.
      3. +
    3. Call memory_brief before substantive work.
      4. +
    4. Call query_link for answer-ready context packets.
      5. +
    5. Call ingest_status after the user drops files into raw/.
      6. +
    6. Use propose_memories before writing durable memories from long notes.
      7. +
    7. Use remember_memory only after the user explicitly asks to remember something.
      8. +
    + 
    User: is Link ready?
+Agent: link_status()
+
+User: brief me from Link before we continue
+Agent: memory_brief(query="current task")
+
+User: query Link for the release plan
+Agent: query_link(query="release plan", budget="small")
    + +

    Core Tool Groups

    + + + + + + + + + + +
    NeedPrimary toolsContract behavior
    Readinesslink_status, validate_wiki, link_operationsReturns safe next actions instead of guessing.
    First usestarter_prompts, ingest_statusProvides natural prompts and exact post-ingest checks.
    Recallmemory_brief, query_link, recall_memory, get_contextReturns ranked memory/wiki context with reasons and budget limits.
    Graphget_graph_summary, get_backlinks, get_graphStarts bounded, then asks before expanding to large exports.
    Memory writespropose_memories, remember_memory, update_memory, set_memory_visibility, review_memoryRequires explicit approval and surfaces duplicate/conflict candidates.
    Auditmemory_log, memory_wins, memory_audit, backup_wikiReports lifecycle and proof signals without raw memory bodies.
    + +

    Write Rules

    +

    Agents should treat Link memory as durable state, not scratch space.

    +
      +
    • Do not call remember_memory unless the user explicitly asks to remember something.
      • +
    • Use propose_memories for transcripts, long notes, or uncertain context.
      • +
    • If a write returns duplicate_candidates, update the existing memory instead of creating another one.
      • +
    • If a write returns conflict_candidates, explain the conflict and ask the user before overriding.
      • +
    • Use review_after for memories that should be re-checked, and expires_at for temporary context.
      • +
    + +

    Sharing Semantics

    +

    scope answers where a memory applies. visibility answers who should see it.

    + + + + + + +
    FieldValuesMeaning
    scopeuser, project, globalControls relevance for recall and project filters.
    visibilityprivate, project, teamControls sharing intent for Git sync and snapshots.
    +

    By default, user/global memories are private and project memories are project-visible. lnk team-sync blocks ready status if private memories would be included in a broad Git share. lnk snapshot --include-memories still excludes private memories unless --include-private-memories is explicitly passed.

    +

    Use set_memory_visibility or lnk set-memory-visibility only after explicit user approval when an existing memory should move between private, project, and team sharing intent.

    + +

    Budgets

    +

    query_link supports small, medium, and large budgets. Each packet includes why an item was selected, estimated tokens, has_more flags, and follow-up actions. This keeps agents from reading a 500-page or 10,000-page wiki just to answer one task.

    + 
    query_link(query="what should I know before changing release docs?", budget="small")
    +
    +
    +
    + + + + diff --git a/docs/obsidian.html b/docs/obsidian.html new file mode 100644 index 0000000..74c7f35 --- /dev/null +++ b/docs/obsidian.html @@ -0,0 +1,91 @@ + + + + + + + Link - Obsidian + + + + + + + + + + + + + +
    +
    + Plain Markdown +

    Open Link in Obsidian when you want a richer notes UI.

    +

    Link owns the memory lifecycle. Obsidian can be a comfortable editor and graph viewer for the same local Markdown files.

    +
    +
    + +
    +
    + +
    +

    Import An Existing Obsidian Vault

    +

    Use lnk import-obsidian when you already have project notes in Obsidian and want Link agents to ingest them as source-backed knowledge. Link copies Markdown notes into raw/obsidian/<vault>/, skips Obsidian plugin state, and blocks notes with secret-looking values before writing them.

    + 
    lnk init ~/link
+lnk import-obsidian ~/Documents/ObsidianVault ~/link
+lnk ingest-status ~/link
    +

    The import does not silently create durable memories. It stages raw source notes, then the normal ingest and proposal workflow decides what becomes wiki knowledge or reviewed memory.

    + +

    Open The Link Wiki

    +

    In Obsidian, choose Open folder as vault and select your Link wiki folder:

    + 
    ~/link/wiki
    +

    For a project-local install, open that project's wiki/ folder instead. Link uses regular Markdown files, YAML frontmatter, and [[wikilinks]], so Obsidian can read the pages directly.

    + +

    Edit Safely

    +

    Prefer editing prose, titles, aliases, tags, summaries, and source notes. Be careful with lifecycle fields on memory pages, such as status, review_status, scope, project, and source, because agents use those fields to decide what is safe to recall.

    +
    + Memory rule + Use Link commands or MCP tools for durable memory writes when possible. They check duplicates, conflicts, review state, and audit logs. +
    + +

    Keep Link Indexes Current

    +

    After manual Obsidian edits, rebuild derived indexes and validate the wiki before asking agents to rely on the new content:

    + 
    lnk rebuild-index ~/link
+lnk rebuild-backlinks ~/link
+lnk validate ~/link
+lnk health ~/link
    +

    The local web viewer is still useful for Link-specific views like health, ingest, memory review, captures, and MCP-ready query context. Obsidian is an editor/viewer for the same underlying files, not a replacement for Link's validation and memory lifecycle.

    +
    +
    +
    + +
    +
    Concepts · CLI reference · Security · If Link helps your agents remember better, star it on GitHub.
    +

    The installed Link product has no telemetry. This public docs site may use lightweight analytics to understand install interest.

    +
    + + diff --git a/docs/scale.html b/docs/scale.html new file mode 100644 index 0000000..403edba --- /dev/null +++ b/docs/scale.html @@ -0,0 +1,114 @@ + + + + + + + Link - Scale + + + + + + + + + + + + + +
    +
    + Scale model +

    Link is built for bounded local memory, not full-folder context dumps.

    +

    Large local wikis should stay usable because agents receive budgets, graph overviews open bounded first, search uses SQLite FTS when available, and unchanged pages are reused from the persistent cache.

    +
    +
    + +
    +
    + +
    +

    Practical Promise

    +

    Link is local personal memory software. The expected sweet spot is a real user's working wiki: hundreds to thousands of Markdown pages, raw sources, durable memories, and graph links. The product is designed so agents do not need to enumerate that whole corpus for normal work.

    +
    +

    Search

    SQLite FTS5 is used when Python provides it. If SQLite FTS is unavailable, Link falls back to a token index and reports that backend in status and benchmark output.

    +

    Cache reuse

    Persistent page-cache records let repeated runs reuse unchanged parsed pages instead of rereading everything after every command.

    +

    Graph

    Large graphs open as a bounded high-signal overview first. Users can search, filter, focus neighborhoods, or explicitly load more when they need it.

    +

    Agent context

    MCP and CLI query packets use small, medium, and large budgets with follow-up actions instead of dumping every page into the model.

    +
    + +

    Bounded Surfaces

    +

    The important scale behavior is not "can Link list every page?" It is "does the default agent and UI path stay bounded?"

    +
    +
    SurfaceDefault behaviorExpansion path
    +
    query_linkReturns a budgeted context packet with why each item was selected.Use follow-up actions for more memory, search, context, or graph detail.
    +
    get_graph_summaryReturns a bounded topic or high-degree graph neighborhood.Increase limit/depth or request the full graph only when needed.
    +
    Local graph UIStarts capped with sparse labels and motion limits for large wikis.Use type filters, node search, focused neighborhoods, fullscreen, and explicit all-data loading.
    +
    All pagesLists a bounded window grouped by page type.Use paging, search, and type filters instead of scrolling the whole wiki.
    +
    HealthShows readiness, validation, interrupted writes, backend, and cache reuse.Run repair commands only when health points to a specific issue.
    +
    + +

    Measure Locally

    +

    Use lnk benchmark on your real wiki. It reports cache time, persistent-cache reuse, search backend, search/query timing, graph payload shape, and recommendations.

    + 
    lnk benchmark "agent memory"
+lnk health
+lnk status --validate
    +

    From a source checkout, use a synthetic 10k-page check without touching your real wiki:

    + 
    python3 scripts/smoke_large_wiki.py --pages 10000
    +

    The smoke script prints the generated wiki path, the local viewer command, and graph URLs so you can inspect browser behavior manually.

    + +

    Large Wiki Habits

    +
      +
    • Prefer brief, query, and graph-summary over full exports.
      • +
    • Use page-type filters and search before opening full graph data.
      • +
    • Run lnk health after ingest or broad manual edits.
      • +
    • Run lnk doctor --fix only when health or validation points to a repairable issue.
      • +
    • Keep private raw sources out of Git; use snapshot, team-sync, and compliance-export for reviewable sharing paths.
      • +
    + +

    Current Limits

    +

    Link is not pretending to be an enterprise search cluster. These are the current boundaries to understand before betting a huge corpus on it:

    +
      +
    • Indexes are local and process-owned. Very large wikis still use memory proportional to the page/index size.
      • +
    • The SQLite FTS index is built locally from wiki pages rather than maintained as a separate hosted service.
      • +
    • The local HTTP viewer is for personal loopback use, not a multi-user hosted deployment.
      • +
    • Full graph exports are intentionally not the default for large wikis. Use bounded graph summaries first.
      • +
    • At tens of thousands of pages and beyond, persistent on-disk indexing and chunked graph loading become the next engineering frontier.
      • +
    +

    The near-term direction is clear: preserve the plain Markdown storage model while making cache, search, graph, and validation paths more incremental over time.

    +
    +
    +
    + +
    +
    CLI · UI · Troubleshooting · If Link helps your agents remember better, star it on GitHub.
    +

    The installed Link product has no telemetry. This public docs site may use lightweight analytics to understand install interest.

    +
    + + diff --git a/docs/security.html b/docs/security.html index 2f9b447..87f7d95 100644 --- a/docs/security.html +++ b/docs/security.html @@ -21,10 +21,13 @@
    Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -48,7 +51,9 @@

    Your agent memory should belong to you.

    Secret handling HTTP boundary Backups + Team review Before sharing + Reporting

    Privacy Model

    @@ -62,10 +67,12 @@

    Privacy Model

    The public GitHub Pages documentation may use lightweight analytics to understand install interest. It does not run inside Link, read local wiki data, or capture source/memory content.

    Secret Handling

    -

    Link scans raw sources, captures, release files, and public artifacts for secret-looking values. It detects common API keys and token formats, warns without logging secret values, and refuses normal ingest guidance when raw safety cannot be established.

    - 
    link ingest-status
-link capture-inbox
-link redact-capture raw/memory-captures/<capture>.md
+        
    Link scans raw sources, captures, wiki pages, release files, and public artifacts for secret-looking values. It detects common API keys, provider tokens, JWTs, private key blocks, and registry credentials, warns without logging secret values, and refuses normal ingest guidance when raw safety cannot be established. Validation and doctor checks also fail if a secret-looking value is already present in a wiki page before the local UI or MCP tools can serve it as context.
    
+        
    lnk ingest-status
+lnk capture-inbox
+lnk redact-capture raw/memory-captures/<capture>.md
+lnk validate
+lnk doctor
 python3 scripts/check_release_hygiene.py
    
         
    
           Rule
@@ -77,19 +84,25 @@ 
    HTTP Boundary
    
         
    HTTP write actions require X-Link-Local-Action: true. Responses include X-Link-API-Version. Proposal analysis does not write pages.
    
 
         
    Backups
    
-        
    link backup and MCP backup_wiki write local .link-backups/ archives. Raw sources are excluded unless explicitly requested.
    
-        
    link backup
-link backup --include-raw
-link doctor --fix
    
+        
    lnk backup and MCP backup_wiki write local .link-backups/ archives. Raw sources are excluded unless explicitly requested.
    
+        
    lnk backup
+lnk backup --include-raw
+lnk doctor --fix
    
         
    Run a backup before broad repair work or large generated changes.
    
 
+        
    Team Review
    
+        
    For small teams, evaluate Link as a local-first tool first: each developer runs their own CLI/MCP server, then reviewed wiki/ pages can be shared through Git when the team explicitly wants shared memory.
    
+        
    Open the team security checklist
    
+
         
    Before Sharing A Repo Or Wiki
    
         
    python3 link.py doctor
 python3 link.py validate
 python3 scripts/check_release_hygiene.py
 git diff --check
    
         
    Use git push, git archive, or clean build artifacts for public sharing. Do not zip a whole working directory; ignored local files, .git/, caches, raw sources, and build outputs can be included by accident.
    
-        
    See SECURITY.md for vulnerability reporting.
    
+        
    Reporting Security Issues
    
+        
    Use a private maintainer contact channel first. Do not post secrets, private wiki content, raw source files, or exploitable details in public GitHub issues. If a public issue is the only available path, keep it high level and ask for a private follow-up channel.
    
+        
    See SECURITY.md for the current reporting policy.
    diff --git a/docs/skills.html b/docs/skills.html new file mode 100644 index 0000000..8400477 --- /dev/null +++ b/docs/skills.html @@ -0,0 +1,108 @@ + + + + + + + Link - Skills + + + + + + + + + + + + + +
    +
    + No MCP required +

    Lazy-load Link through skills.

    +

    Official skills are small CLI workflows an agent can load only when needed: health, retrieval, ingest, and memory lifecycle.

    +
    +
    + +
    +
    + +
    +

    Why Skills

    +

    MCP gives Link structured tool calls, but it should not be the only path. If an agent can run local commands, it can use Link through lnk without an MCP server, background viewer, or extra client configuration. From a source checkout, the same workflows work with python3 link.py.

    +
    + lnk serve is optional +

    The web viewer is only for humans. Skills, CLI commands, and MCP tools all read the same local Markdown wiki directly.

    +
    + +

    Included Skills

    +

    The repo ships official skill folders under skills/:

    + + + + + + + + + + +
    SkillUse it forFirst command
    link-healthReadiness, interrupted writes, backups, repair, validation.lnk health
    link-retrieveBounded query packets, briefs, graph summaries, benchmarks.lnk query "..."
    link-ingestRaw source ingest, stale sources, memory proposals, post-ingest checks.lnk ingest-status
    link-memoryRemember, recall, review, explain, update, archive, restore, forget.lnk brief "..."
    + +

    Use Them

    +

    Point your agent at the skill folder it supports, or copy the relevant SKILL.md into that agent's local skill directory.

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

    Then use natural prompts that map to the skills:

    + 
    is Link ready?
+brief me from Link before we continue
+query Link for the release process
+ingest raw/notes.md into Link
+remember that I prefer short release notes
    + +

    Rules For Agents

    +
      +
    • Prefer lnk health when readiness is unclear.
      • +
    • Prefer lnk query, lnk brief, and lnk graph-summary over reading the whole wiki.
      • +
    • Use lnk ingest-status before touching raw sources.
      • +
    • Do not silently create durable memory; use lnk remember only when the user asks or approves a proposal.
      • +
    • Run lnk validate and lnk health after ingest or broad wiki edits.
      • +
    +

    Use MCP when you want structured tool calls inside an MCP client. Use skills when you want a lightweight, lazy-loaded CLI workflow.

    +
    +
    +
    + + + + diff --git a/docs/team-security.html b/docs/team-security.html new file mode 100644 index 0000000..006be3f --- /dev/null +++ b/docs/team-security.html @@ -0,0 +1,129 @@ + + + + + + + Link - Team Security Review + + + + + + + + + + + + + +
    +
    + Team review +

    Local agent memory without a new cloud data boundary.

    +

    A practical checklist for engineering leads and security reviewers evaluating Link for a small team, repo, or design partner pilot.

    +
    +
    + +
    +
    + +
    +

    Deployment Model

    +

    Link is designed as a local personal or repo-local memory layer. Each developer runs the CLI, optional skills, and MCP server on their own machine. The web viewer is optional and only serves the local UI.

    +
    + No server dependency + lnk serve is only the human web viewer. CLI, skills, and MCP access work directly against local Markdown files when the viewer is closed. +
    + 
    brew install gowtham0992/link/link
+lnk init ~/link
+lnk health ~/link
+lnk connect codex ~/link
    + +

    Data Boundaries

    +
      +
    • raw/ contains private source material and is gitignored by default.
      • +
    • wiki/ contains structured Markdown pages, memories, logs, and backlinks.
      • +
    • link-mcp talks over stdio to the local agent client. It does not require serve.py.
      • +
    • The installed product has no telemetry, hosted backend, or outbound API calls.
      • +
    • Secret-looking values are scanned before capture, ingest, Obsidian import, and doctor checks.
      • +
    + 
    lnk ingest-status ~/link
+lnk doctor ~/link
+lnk validate ~/link
    + +

    Memory Approval Gates

    +

    Agents can propose memories, but durable memory should be explicit and reviewable. Link keeps memory as Markdown with type, scope, visibility, project, source, review status, optional review dates, and optional expiry dates.

    + 
    lnk propose-memories raw/notes.md ~/link
+lnk memory-inbox ~/link
+lnk review-memory memory-name ~/link
+lnk archive-memory memory-name ~/link --reason stale
    +

    For temporary context, use expires_at. For decisions that should be re-confirmed, use review_after. For team handoff, keep personal context at visibility: private and only mark memories project or team after the user explicitly approves sharing them.

    + +

    Team Sharing Pattern

    +

    The safest early team workflow is Git-backed sharing of reviewed wiki pages. Keep raw sources local unless the team explicitly decides to share them.

    + 
    lnk team-sync ~/link --remote git@example.com:team/link-memory.git
+lnk compliance-export ~/link --output link-audit.json
+lnk backup ~/link
    +

    lnk team-sync is read-only. It checks Git state, raw-source protection, review readiness, and whether active visibility: private memories would be swept into a broad git add wiki. It prints paste-safe commands instead of pushing data for you.

    + +

    Audit Packet

    +

    lnk compliance-export creates a redacted JSON packet for review. It includes readiness, validation status, memory review counts, operation markers, recent audit log metadata, and safe next actions. Raw source contents and memory bodies are excluded.

    + 
    lnk compliance-export ~/link --output link-audit.json
+lnk wins ~/link
+lnk memory-log ~/link
    + +

    Current Limits

    +
      +
    • Link is local-first and single-user by default. It is not an SSO-backed team server.
      • +
    • The local web viewer has no authentication and should not be exposed beyond loopback.
      • +
    • Git sharing is intentionally manual so teams see exactly what is being committed.
      • +
    • Access control is currently based on local files, project filters, and review workflow, not centralized RBAC.
      • +
    + +

    Security Review Checklist

    +
      +
    1. Run lnk health ~/link and verify readiness is green.
      2. +
    2. Run lnk doctor ~/link and resolve secret or validation warnings.
      3. +
    3. Run lnk compliance-export ~/link --output link-audit.json.
      4. +
    4. Confirm raw/, backups, caches, and local MCP Python markers are ignored by Git.
      5. +
    5. Review wiki/log.md, lnk memory-log ~/link, and lnk wins ~/link.
      6. +
    6. Only share reviewed wiki/ pages whose memories are marked visibility: project or visibility: team.
      7. +
    +
    +
    +
    + + + + diff --git a/docs/troubleshooting.html b/docs/troubleshooting.html index 7f17b77..f570f74 100644 --- a/docs/troubleshooting.html +++ b/docs/troubleshooting.html @@ -21,10 +21,13 @@
    Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -55,31 +58,32 @@

    Start with status, then repair deliberately.

    Is Link Ready?

    - 
    link health
-link status --validate
-link doctor
-link next
    + 
    lnk health
+lnk status --validate
+lnk doctor
+lnk next

    If link is not on your PATH, run from the source checkout with python3 link.py, or add ~/.local/bin to your shell path.

    MCP Is Not Visible

    - 
    link verify-mcp
+        
    lnk verify-mcp
 python3 -m pip index versions link-mcp
    
         
    Restart the MCP client after changing its config. If your installer printed a venv Python path, use that exact path in the MCP config.
    
+        
    You do not need lnk serve or serve.py running for MCP. The web viewer is separate from the MCP server.
    
 
         
    Ingest Is Blocked
    
-        
    link ingest-status
    
+        
    lnk ingest-status
    
         
    Blocked ingest usually means a raw source has secret-looking values, cannot be read safely, or source representation counts may be incomplete. Redact or fix the local file, then ask the agent to ingest again.
    
 
         
    Interrupted Writes
    
-        
    link operations
-link validate
-link doctor --fix
    
+        
    lnk operations
+lnk validate
+lnk doctor --fix
    
         
    If a memory write was interrupted, Link leaves a marker under wiki/.link-operations/. Inspect it before deleting anything manually, then validate the wiki and repair generated indexes if needed.
    
 
         
    Graph Is Stale
    
-        
    link rebuild-index
-link rebuild-backlinks
-link validate
    
+        
    lnk rebuild-index
+lnk rebuild-backlinks
+lnk validate
    
         
    Run this after manual Obsidian edits, hand-written wikilinks, or a failed ingest.
    
 
         
    Demo Looks Stale
    
@@ -90,10 +94,10 @@ 
    Demo Looks Stale
    
         
    The current generated demo should include three raw sources, source-backed wiki pages, one starter memory, one exploration, current backlinks, and schema v1.
    
 
         
    The Wiki Feels Slow
    
-        
    link benchmark "agent memory"
-link graph-summary "agent memory" --limit 40 --depth 1
    
+        
    lnk benchmark "agent memory"
+lnk graph-summary "agent memory" --limit 40 --depth 1
    
         
    Large graph views intentionally open bounded first. Use type filters, node search, depth controls, and explicit all-data loading only when you need search or filtering across every page.
    
-        
    If link health or link benchmark shows low persistent-cache reuse after repeated runs, inspect recently edited pages or generated files that are changing on every request.
    
+        
    If lnk health or lnk benchmark shows low persistent-cache reuse after repeated runs, inspect recently edited pages or generated files that are changing on every request.
    
         
    From a source checkout, use the synthetic smoke script when you want local scale evidence without touching your real wiki:
    
         
    python3 scripts/smoke_large_wiki.py --pages 10000
    
 
diff --git a/docs/ui.html b/docs/ui.html
index e3e64ba..eabe69a 100644
--- a/docs/ui.html
+++ b/docs/ui.html
@@ -21,10 +21,13 @@
     
    
       Start
       Why
+      Scale
       UI
       Concepts
       MCP
+      Contract
       CLI
+      Skills
       API
       Security
       Contribute
@@ -82,14 +85,15 @@ 
    Graph At Scale
    
         
 
         
    Health Page
    
-        
    Open /health when the wiki feels wrong. It gathers the same readiness signals as link status --validate, plus persistent-cache reuse, interrupted operation markers, and repair commands you can copy back into your terminal or agent chat.
    
+        
    Open /health when the wiki feels wrong. It gathers the same readiness signals as lnk status --validate, plus persistent-cache reuse, interrupted operation markers, and repair commands you can copy back into your terminal or agent chat.
    
 
         
    Start It
    
-        
    link serve
+        
    lnk serve
 
 # from a source checkout
 python3 link.py serve link-demo
    
         
    The server binds to 127.0.0.1 and is intended for local use. Do not expose it to the internet without adding your own authentication layer.
    
+        
    This viewer is optional. CLI commands, official skills, and MCP clients keep working after you close the browser or stop serve.py.
    diff --git a/docs/why-link.html b/docs/why-link.html index 36b9b09..9d28d8e 100644 --- a/docs/why-link.html +++ b/docs/why-link.html @@ -21,10 +21,13 @@
    Start Why + Scale UI Concepts MCP + Contract CLI + Skills API Security Contribute @@ -45,6 +48,7 @@

    Link is not a notes app. It is local memory for agents.

    ' '
    4' '

    Review later

    Use the inbox and explain views to review, archive, update, or forget memories.

    ' - 'link memory-inbox
    ' + 'lnk memory-inbox' '
    ' ) diff --git a/mcp_package/link_core/wiki.py b/mcp_package/link_core/wiki.py index f50e25e..69f5ecb 100644 --- a/mcp_package/link_core/wiki.py +++ b/mcp_package/link_core/wiki.py @@ -1040,7 +1040,7 @@ def rebuild_index( "next_actions": [ { "tool": "rebuild_backlinks", - "command": "link rebuild-backlinks", + "command": "lnk rebuild-backlinks", "reason": "Regenerated index links change graph edges; rebuild backlinks before validation.", } ], diff --git a/mcp_package/link_mcp/__init__.py b/mcp_package/link_mcp/__init__.py index f3ba7ec..97e5965 100644 --- a/mcp_package/link_mcp/__init__.py +++ b/mcp_package/link_mcp/__init__.py @@ -1,2 +1,2 @@ """Link MCP Server — personal knowledge wiki as MCP tools.""" -__version__ = "1.3.0" +__version__ = "1.4.0" diff --git a/mcp_package/link_mcp/__main__.py b/mcp_package/link_mcp/__main__.py index eec0db0..646621f 100644 --- a/mcp_package/link_mcp/__main__.py +++ b/mcp_package/link_mcp/__main__.py @@ -1,5 +1,5 @@ """Entry point: python -m link_mcp""" -from link_mcp.server import mcp +from link_mcp.server import main if __name__ == "__main__": - mcp.run(transport="stdio") + main() diff --git a/mcp_package/link_mcp/server.py b/mcp_package/link_mcp/server.py index 4cc3ba1..5f9f46f 100644 --- a/mcp_package/link_mcp/server.py +++ b/mcp_package/link_mcp/server.py @@ -27,13 +27,21 @@ import argparse import json import sys +import time from pathlib import Path +from link_core.version import LINK_VERSION + # ── Resolve wiki directory ──────────────────────────────────────────── parser = argparse.ArgumentParser(add_help=False) parser.add_argument("--wiki", default=None) +parser.add_argument("--version", action="store_true") args, _ = parser.parse_known_args() +if args.version: + print(f"link-mcp {LINK_VERSION}") + sys.exit(0) + if args.wiki: WIKI_DIR = Path(args.wiki).expanduser().resolve() else: @@ -42,7 +50,7 @@ if not WIKI_DIR.exists(): print( f"[link-mcp] Wiki not found at {WIKI_DIR}. " - "Initialize Link first with `link init` or `python3 link.py init`, " + "Initialize Link first with `lnk init` or `python3 link.py init`, " "run an integration installer under integrations/*/install.sh, " "or pass --wiki /path/to/wiki.", file=sys.stderr, @@ -97,6 +105,8 @@ # ── In-memory indexes (built on first use, invalidated by mtime) ────── _cache: dict = {} _cache_mtime: float = 0.0 +_cache_checked_at: float = 0.0 +CACHE_MTIME_CHECK_INTERVAL_SECONDS = 0.5 MAX_TEXT_INPUT = 200 MAX_CAPTURE_INPUT = 12000 @@ -120,6 +130,7 @@ recent_memories as _core_recent_memories, resolve_memory_page as _core_resolve_memory_page, set_memory_status as _core_set_memory_status, + set_memory_visibility as _core_set_memory_visibility, slim_memory as _core_slim_memory, top_tags as _core_top_tags, update_memory_page as _core_update_memory_page, @@ -152,6 +163,12 @@ append_log as _core_append_log, utc_timestamp as _core_utc_timestamp, ) +from link_core.memory_log import ( + memory_log_payload as _core_memory_log_payload, +) +from link_core.memory_wins import ( + memory_wins_payload as _core_memory_wins_payload, +) from link_core.operations import ( operation_report as _core_operation_report, ) @@ -167,7 +184,6 @@ from link_core.validation import ( validate_wiki as _core_validate_wiki, ) -from link_core.version import LINK_VERSION from link_core.status import ( link_status as _core_link_status, ) @@ -237,15 +253,25 @@ def _wiki_mtime() -> float: def _clear_cache() -> None: - global _cache, _cache_mtime + global _cache, _cache_mtime, _cache_checked_at _core_close_wiki_cache(_cache) _cache = {} _cache_mtime = 0.0 + _cache_checked_at = 0.0 def _build_cache() -> dict: - global _cache, _cache_mtime + global _cache, _cache_mtime, _cache_checked_at + now = time.monotonic() + if ( + _cache + and CACHE_MTIME_CHECK_INTERVAL_SECONDS > 0 + and now - _cache_checked_at < CACHE_MTIME_CHECK_INTERVAL_SECONDS + ): + return _cache + mtime = _wiki_mtime() + _cache_checked_at = now if _cache and mtime == _cache_mtime: return _cache @@ -295,6 +321,24 @@ def _memory_inbox(limit: int = 20, include_archived: bool = False, project: str ) +def _memory_log(limit: int = 50, include_captures: bool = True) -> dict[str, object]: + return _core_memory_log_payload( + WIKI_DIR, + limit=_parse_limit(limit, default=50), + include_captures=include_captures, + ) + + +def _memory_wins(limit: int = 6, project: str = "") -> dict[str, object]: + limit = _parse_limit(limit, default=6) + return _core_memory_wins_payload( + WIKI_DIR, + limit=limit, + project=project, + records=_memory_records(), + ) + + def _memory_explanation(identifier: str) -> dict[str, object]: return _core_memory_explanation( WIKI_DIR, @@ -529,6 +573,7 @@ def _accept_capture( title: str = "", memory_type: str = "", scope: str = "", + visibility: str = "", tags: str = "", project: str = "", allow_duplicate: bool = False, @@ -556,13 +601,15 @@ def _accept_capture( title=_clean_text_input(title), memory_type=_clean_text_input(memory_type).lower(), scope=_clean_text_input(scope).lower(), + visibility=_clean_text_input(visibility).lower(), tags=tags, ) - result = _write_memory_page( + result = _write_mcp_memory_page( str(memory_args["text"]), title=str(memory_args["title"]), memory_type=str(memory_args["memory_type"]), scope=str(memory_args["scope"]), + visibility=str(memory_args["visibility"] or ""), tags=memory_args["tags"] if isinstance(memory_args["tags"], str) else "", source=str(memory_args["source"]), allow_duplicate=allow_duplicate, @@ -669,6 +716,20 @@ def _set_memory_status(identifier: str, status: str, reason: str = "") -> dict[s return result +def _set_memory_visibility(identifier: str, visibility: str) -> dict[str, object]: + result = _core_set_memory_visibility( + WIKI_DIR, + _clean_text_input(identifier, max_len=300), + _clean_text_input(visibility, max_len=40), + timestamp=_utc_timestamp(), + records=_memory_records(), + log_writer=_append_log, + ) + if result["updated"]: + _clear_cache() + return result + + def _forget_memory(identifier: str, confirm: bool = False) -> dict[str, object]: result = _core_forget_memory_page( WIKI_DIR, @@ -720,10 +781,11 @@ def _update_memory_page( return result -def _write_memory_page( +def _write_mcp_memory_page( text: str, title: str = "", memory_type: str = "note", scope: str = "user", tags: str = "", source: str = "mcp", allow_duplicate: bool = False, allow_conflict: bool = False, project: str = "", + visibility: str = "", review_after: str = "", expires_at: str = "", ) -> dict[str, object]: clean_text = _required_text_input(text, "memory text required", max_len=4000) memory_type, scope = _memory_type_scope(memory_type, scope) @@ -733,6 +795,9 @@ def _write_memory_page( WIKI_DIR, clean_text, title=_clean_text_input(title), memory_type=memory_type, scope=scope, tags=_clean_text_input(tags, max_len=500), source=_clean_text_input(source, max_len=500), + visibility=_clean_text_input(visibility, max_len=40) or None, + review_after=_clean_text_input(review_after, max_len=40) or None, + expires_at=_clean_text_input(expires_at, max_len=40) or None, allow_duplicate=allow_duplicate, allow_conflict=allow_conflict, **options, ) @@ -963,6 +1028,7 @@ def accept_capture( title: str = "", memory_type: str = "", scope: str = "", + visibility: str = "", tags: str = "", project: str = "", allow_duplicate: bool = False, @@ -980,6 +1046,7 @@ def accept_capture( title=title, memory_type=memory_type, scope=scope, + visibility=visibility, tags=tags, project=project, allow_duplicate=allow_duplicate, @@ -1053,6 +1120,29 @@ def memory_inbox(limit: int = 20, include_archived: bool = False, project: str = return json.dumps(_memory_inbox(limit=limit, include_archived=include_archived, project=project), ensure_ascii=False) +@mcp.tool() +def memory_log(limit: int = 50, include_captures: bool = True) -> str: + """List recent memory lifecycle changes. + + Use this when the user asks what Link remembered, updated, reviewed, + archived, restored, forgot, or accepted from captures recently. The result + is metadata from wiki/log.md and does not include raw source or memory + bodies. + """ + return json.dumps(_memory_log(limit=limit, include_captures=include_captures), ensure_ascii=False) + + +@mcp.tool() +def memory_wins(limit: int = 6, project: str = "") -> str: + """Summarize local proof signals for Link memory value. + + Use this when the user asks whether Link is useful, what memory value has + accumulated, or how to demonstrate the local memory loop. The result is + based on local wiki metadata only; Link does not track telemetry. + """ + return json.dumps(_memory_wins(limit=limit, project=project), ensure_ascii=False) + + @mcp.tool() def review_memory(identifier: str, note: str = "") -> str: """Mark a memory as reviewed after user confirmation.""" @@ -1104,6 +1194,21 @@ def update_memory( return json.dumps(result, ensure_ascii=False) +@mcp.tool() +def set_memory_visibility(identifier: str, visibility: str) -> str: + """Change a memory's sharing visibility. + + Use this after explicit user approval when a memory should move between + private, project, and team visibility. This updates frontmatter and logs the + visibility change; it does not expose raw sources or memory bodies in logs. + """ + try: + result = _set_memory_visibility(identifier, visibility) + except ValueError as exc: + return json.dumps({"updated": False, "error": str(exc)}) + return json.dumps(result, ensure_ascii=False) + + @mcp.tool() def archive_memory(identifier: str, reason: str = "") -> str: """Archive a memory without deleting its Markdown page. @@ -1151,6 +1256,9 @@ def remember_memory( allow_duplicate: bool = False, allow_conflict: bool = False, project: str = "", + visibility: str = "", + review_after: str = "", + expires_at: str = "", ) -> str: """Save a local agent memory as a Markdown page. @@ -1160,11 +1268,14 @@ def remember_memory( Potential conflicts are refused unless allow_conflict is true. memory_type: preference, decision, project, fact, or note. scope: user, project, or global. + visibility: private, project, or team. Defaults to private for user/global and project for project-scoped memories. project: optional project key for project-scoped memories. tags: optional comma-separated tags. + review_after: optional YYYY-MM-DD date when this memory should be checked again. + expires_at: optional YYYY-MM-DD date when this memory should leave default recall. """ try: - result = _write_memory_page( + result = _write_mcp_memory_page( memory, title=title, memory_type=memory_type, @@ -1174,6 +1285,9 @@ def remember_memory( allow_duplicate=allow_duplicate, allow_conflict=allow_conflict, project=project, + visibility=visibility, + review_after=review_after, + expires_at=expires_at, ) except ValueError as exc: return json.dumps({"created": False, "error": str(exc)}) diff --git a/mcp_package/pyproject.toml b/mcp_package/pyproject.toml index 1b5da91..30fc96a 100644 --- a/mcp_package/pyproject.toml +++ b/mcp_package/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "link-mcp" -version = "1.3.0" +version = "1.4.0" description = "MCP server for Link local agent memory — remember, recall, search, context, and graph traversal" readme = "README.md" license = { text = "MIT" } diff --git a/mcp_package/server.json b/mcp_package/server.json index 30032df..3c62355 100644 --- a/mcp_package/server.json +++ b/mcp_package/server.json @@ -6,12 +6,12 @@ "url": "https://github.com/gowtham0992/link", "source": "github" }, - "version": "1.3.0", + "version": "1.4.0", "packages": [ { "registryType": "pypi", "identifier": "link-mcp", - "version": "1.3.0", + "version": "1.4.0", "transport": { "type": "stdio" } diff --git a/packaging/homebrew/Formula/link.rb b/packaging/homebrew/Formula/link.rb index 797e258..4d138a9 100644 --- a/packaging/homebrew/Formula/link.rb +++ b/packaging/homebrew/Formula/link.rb @@ -21,24 +21,24 @@ def install (libexec/"mcp_package").mkpath (libexec/"mcp_package").install "mcp_package/link_core" - (bin/"link").write <<~SH + (bin/"lnk").write <<~SH #!/bin/sh - exec "#{python3}" "#{libexec}/link.py" "$@" + LINK_CLI_COMMAND=lnk exec "#{python3}" "#{libexec}/link.py" "$@" SH end def caveats <<~EOS Try Link: - link demo - link serve link-demo + lnk demo + lnk serve link-demo Then open: http://127.0.0.1:3000 http://127.0.0.1:3000/graph To create a personal wiki: - link init ~/link + lnk init ~/link For MCP clients, install link-mcp with the agent installer or a venv: python3 -m venv ~/.link-mcp-venv @@ -47,9 +47,9 @@ def caveats end test do - system bin/"link", "--version" - system bin/"link", "demo", testpath/"link-demo", "--force" - system bin/"link", "validate", testpath/"link-demo" - system bin/"link", "status", "--validate", testpath/"link-demo" + system bin/"lnk", "--version" + system bin/"lnk", "demo", testpath/"link-demo", "--force" + system bin/"lnk", "validate", testpath/"link-demo" + system bin/"lnk", "status", "--validate", testpath/"link-demo" end end diff --git a/packaging/homebrew/README.md b/packaging/homebrew/README.md index 05ecb2e..eae3cef 100644 --- a/packaging/homebrew/README.md +++ b/packaging/homebrew/README.md @@ -32,8 +32,8 @@ Validate locally: brew audit --strict --online gowtham0992/link/link brew install --build-from-source gowtham0992/link/link brew test gowtham0992/link/link -link --version -link demo +lnk --version +lnk demo ``` Then push the tap repo: diff --git a/scripts/check_tool_contract.py b/scripts/check_tool_contract.py index 0cacb16..a7a4064 100644 --- a/scripts/check_tool_contract.py +++ b/scripts/check_tool_contract.py @@ -16,6 +16,8 @@ "brief", "capture-inbox", "capture-session", + "connect", + "compliance-export", "delete-capture", "demo", "doctor", @@ -23,10 +25,13 @@ "forget-memory", "graph-summary", "health", + "import-obsidian", "ingest-status", "init", "memory-audit", "memory-inbox", + "memory-log", + "wins", "migrate", "next", "operations", @@ -40,10 +45,16 @@ "recall", "redact-capture", "remember", + "restore-backup", "restore-memory", "review-memory", "serve", + "set-memory-visibility", + "share", + "snapshot", "status", + "team-sync", + "try", "update-memory", "validate", "version", @@ -71,7 +82,9 @@ "memory_audit", "memory_brief", "memory_inbox", + "memory_log", "memory_profile", + "memory_wins", "migrate_wiki", "propose_memories", "query_link", @@ -83,6 +96,7 @@ "restore_memory", "review_memory", "search_wiki", + "set_memory_visibility", "starter_prompts", "update_memory", "validate_wiki", @@ -165,8 +179,10 @@ def _missing_cli_reference(path: Path = ROOT / CLI_DOC_PATH) -> list[str]: missing: list[str] = [] for command in sorted(DOCS_CLI_COMMANDS): command_tokens = ( + f"`lnk {command}", f"`link {command}", f"`python3 link.py {command}", + f"lnk {command}", f"link {command}", f"python3 link.py {command}", ) diff --git a/scripts/smoke_first_use.py b/scripts/smoke_first_use.py index fc30c0e..a3892ea 100644 --- a/scripts/smoke_first_use.py +++ b/scripts/smoke_first_use.py @@ -76,7 +76,7 @@ def run_smoke(work_dir: Path, python: str = sys.executable) -> None: "prompts did not start with readiness guidance", ) require( - any(str(command).startswith("link health ") for command in init_prompts.get("commands", [])), + any("health" in str(command).split() for command in init_prompts.get("commands", [])), "prompts did not include readiness command", ) init_welcome = run_json("welcome", str(init_target), "--json", python=python) diff --git a/scripts/smoke_http_viewer.py b/scripts/smoke_http_viewer.py index f1e2efb..7ab8698 100644 --- a/scripts/smoke_http_viewer.py +++ b/scripts/smoke_http_viewer.py @@ -144,7 +144,10 @@ def run_smoke(work_dir: Path, python: str) -> None: require(status == 200, "health page did not return 200") require("Health" in health_html, "health page did not render") require("Repair Commands" in health_html, "health page did not show repair commands") - require("link operations" in health_html, "health page did not include operation inspection guidance") + require( + "lnk operations" in health_html or "link.py operations" in health_html, + "health page did not include operation inspection guidance", + ) status, headers, status_payload = request_json(base_url, "/api/status?validate=true") require(status == 200, "status API did not return 200") diff --git a/serve.py b/serve.py index 70146c0..3064112 100644 --- a/serve.py +++ b/serve.py @@ -6,6 +6,7 @@ import html import http.server import json +import os import re import socketserver import sys @@ -53,6 +54,12 @@ append_log as _core_append_log, utc_timestamp as _core_utc_timestamp, ) +from link_core.memory_log import ( + memory_log_payload as _core_memory_log_payload, +) +from link_core.memory_wins import ( + memory_wins_payload as _core_memory_wins_payload, +) from link_core.markdown import ( markdown_to_html as _core_markdown_to_html, ) @@ -74,6 +81,9 @@ from link_core.version import ( LINK_VERSION, ) +from link_core.mcp_verify import ( + set_link_command_override as _core_set_link_command_override, +) from link_core.web_assets import CSS # noqa: F401 - kept as serve.CSS for tests and compatibility from link_core.web_memory import ( memory_dashboard_next_actions as _core_memory_dashboard_next_actions, @@ -85,8 +95,10 @@ render_captures_page as _core_render_captures_page, render_inbox_page as _core_render_inbox_page, render_memory_explanation_page as _core_render_memory_explanation_page, + render_memory_log_page as _core_render_memory_log_page, render_memory_audit_page as _core_render_memory_audit_page, render_memory_dashboard_page as _core_render_memory_dashboard_page, + render_memory_wins_page as _core_render_memory_wins_page, render_profile_page as _core_render_profile_page, ) from link_core.web_layout import ( @@ -563,6 +575,9 @@ def _remember_memory_from_web(payload: dict[str, object]) -> dict[str, object]: _clean_text_input(payload.get("source") or "web approval", max_len=500), _utc_timestamp(), project=_clean_text_input(payload.get("project"), max_len=80) or None, + visibility=_clean_text_input(payload.get("visibility"), max_len=30) or None, + review_after=_clean_text_input(payload.get("review_after"), max_len=40) or None, + expires_at=_clean_text_input(payload.get("expires_at"), max_len=40) or None, records=_memory_records(), allow_duplicate=False, allow_conflict=False, @@ -763,6 +778,23 @@ def _memory_audit(limit: int = 10, project: str | None = None) -> dict[str, obje return payload +def _memory_log(limit: int = 50, include_captures: bool = True) -> dict[str, object]: + return _core_memory_log_payload( + WIKI_DIR, + limit=max(1, min(limit, 200)), + include_captures=include_captures, + ) + + +def _memory_wins(limit: int = 6, project: str | None = None) -> dict[str, object]: + return _core_memory_wins_payload( + WIKI_DIR, + limit=max(1, min(limit, 50)), + project=project, + records=_memory_records(), + ) + + def _json_for_script(data) -> str: """Serialize JSON for direct embedding inside a