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. Call starter_prompts when a user asks what to try first.
  3. Call memory_brief before substantive work.
  4. Call query_link for answer-ready context packets.
  5. Call ingest_status after the user drops files into raw/.
  6. Use propose_memories before writing durable memories from long notes.
  7. Use remember_memory only after the user explicitly asks to remember something.
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")