Memory that never forgets where it put things

Your agent's memory is a search over its own files. It finds the documents you put in its memory/ folder and its past conversations by their words, and by their meaning too with a model that runs on your computer, and keeps notes of its own that it reads at every message.

lnk agent memory start        # Link Memory over the files of your agent
lnk agent memory              # which engine, and where your agent reaches it
lnk agent memory stop         # stop serving it, and your files stay

Start it

Your agent's first lnk agent start offers it, and lnk agent tool add memory does the same as memory start. start restarts your agent if it's running as a service; one running in a terminal keeps what it had until you start it again there, and start says so. It says where the notes it keeps are, and --agent <name> picks another agent.

What it needs

You need an agent, and lnk agent memory start adds Link Memory if it's missing. Searching by meaning also takes an embedding model, a download of a few hundred megabytes. Nothing costs anything, because it all runs on your computer.

Search by meaning

An embedding model lets a question find a note that shares none of its words.

lnk model install qwen3-embedding   # the embedding model, through Ollama

Then "what did I plant last spring" finds "tomatoes, April, the back bed". Nothing needs a restart: memory finds the model the next time it starts, once your agents have left it idle.

By words only

Without the model, a search is by words only, and says so and how to add the model. To search by words only on purpose, set [tool.memory] model = "none" in the agent's spec.

The first time

The first time, Link Memory embeds your files in the background, newest first. Meanwhile a search is by meaning over what's done and by words over the rest, and says how far it got. After that it embeds only what's new or changed, on your computer's CPU or GPU, at no cost.

What it finds

Your agent can search what's in its files folder's memory/, and its past conversations. Nothing else of the folder is searched: your agent reads the rest with file, but memory doesn't index it, so a search finds only what you chose to give it, on every machine alike.

# a file your agent can find now
cp ~/Notes/garden.md ~/Link/Agents/main/Home/memory/
# a PDF or a Word document too, by the text inside it
cp ~/Documents/tax-return-2025.pdf ~/Link/Agents/main/Home/memory/

What it reads

That means markdown, text, JSON, CSV, YAML, HTML and the like, up to 1 MiB each; PDFs (.pdf) and Word documents (.docx) up to 32 MiB, by the first 2 MiB of their text, once you add the plugin that reads them (Read PDFs and Word documents); and in chats/ each conversation's conversation.md.

What it finds by name

A PDF or document with no text to read, such as a scan, or with the plugin not added, is found by its name alone, and a search's reply says why. Each result says whether it's a file or a conversation. What you add, change or delete is found at the next call, with nothing to rebuild.

Memory from before

Memory from before this indexed the whole files folder. At its first start after, it drops what's outside memory/ and the conversations from its index, and its next search says so once: move what you want found into memory/.

A conversation's copy

A conversation's copy holds what was said up to the agent's last answer, without the tools' calls and answers. So a search finds what was said earlier in the chat you're in, and never the question it's searching for.

A conversation with no copy on disk

A conversation Link Harness keeps compact, or in a store driver ([storage] conversations in its spec), has no conversation.md on disk: memory makes the same copy itself, from its messages, found at the path the file would have. It's made again when the conversation grows. For a driver's, memory's sandbox reads the driver's program, as Link Harness's does.

Kept off its folder

Where your machine keeps its conversations, its instructions or its memory somewhere other than its folder (in SQLite, a bucket, or a store off the machine, as machine.toml's [storage] says), memory reads and writes them through the agent's storage bridge, as the agent, while it runs: its conversations, its notes, and a copy of its index kept with its memory, so another machine it moves to finds the index it left.

Let it take notes

Your agent notes for itself what it should keep in mind in every conversation, and Link Harness puts its notes in its prompt.

# what it noted, a line each: edit it as any file
cat ~/Link/Agents/main/Agent/memory/notes.md

Tell it "remember that my sister is Maya" and it calls remember, which adds a line to memory/notes.md, changes one or forgets one. The notes stay under 4 KB, so they fit in every prompt: past that, remember refuses and your agent changes or forgets a note first. [tool.memory] notes in its spec sets how large.

Notes across conversations

Conversation history and saved notes are separate. A fact repeated in the CLI may only be in that conversation's transcript. Saving it with remember makes it available to the same agent in a fresh CLI chat or on Discord, Slack and other connections. Deleting a conversation does not delete these notes. The agent is instructed to save stable owner facts during the turn and confirm saving only after the call succeeds; the model still has to make that call. Check notes.md to verify it.

What it writes

remember writes nothing else, and where its sandbox file keeps instructions/ read only, there is no remember.

How your agent calls it

Your agent searches, reads and lists its memory through four calls, and none of them changes a file. A fifth, remember, writes its notes and nothing else.

search and read

search finds documents by their words and their meaning, best first, each with a snippet, and read gives a document, whole or some lines of it.

list

list gives the documents, the most recently changed first. With since it gives what changed, so an agent catches up at the start of a session.

links gives what a document links to and what links to it, from markdown links and wiki links ([[Other note]]), and what it links to that memory doesn't hold: the first 200 of each.

How much a call gives

Each call gives at most about 6,000 tokens and says where it stopped, so the next call can carry on from there.

In each harness

Link Harness calls memory by itself, as memory__search and the rest (Link Harness). A harness from outside Link finds it in its own MCP settings, as the server memory, added at each start.

A skill's file

Link Harness reads a skill's SKILL.md with read when a task needs it (skills), by its path, skills/<name>/SKILL.md. Memory reads a text file in skills/ straight from the folder, never through a link, but never indexes it, so no search or listing gives one. A skill kept in memory/ is listed by its folder, since every skill's file is SKILL.md.

Through its proxy

Your agent reaches it only through its proxy, so not with --network-mode host or without [internet]. To try it as your agent would, the first command prints the address your agent calls, and the second lists every call.

lnk agent harness run --harness link -- sh -c 'echo $LNK_MEMORY'
lnk sandbox log               # every call, with the other calls of your agent

More about it

Agents Security has the guarantees and gaps, and Agents Decisions why it works this way. To work on its code, see Developing Link Memory, and when it doesn't find a file or search by meaning, Troubleshooting.

Docs

  • Developing: lnk-link-memory is Link Memory, the memory engine a Link agent uses by default: an MCP server over stdio that searches, reads and lists the agent's files and past conversations, keyless and local
  • Decisions: Why Link Memory is named, writes, indexes, is sandboxed and searches as it does
  • Troubleshooting: What to do when your agent's memory isn't served, doesn't find a file or searches by words only (Link Memory)