Developing
lnk-memory-tool 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. How to use it,
and why it works the way it does:
Link Memory.
What it reads and writes
It speaks Link's memory engine contract (link_memory_tool_contract),
whose install, command and serve-many its actions.toml lists under
[implements], and any harness reaches it as a tool. It reads only its folder, writes only the
agent's notes there when Link names them (--notes), and never follows
a link out of it.
What its command prints
Its command prints a serve line of its own. Its embedding model and
the most a search gives are the agent's spec's, from LNK_MEMORY_SPEC,
else qwen3-embedding and 6000 tokens, and none searches by words
only, with no model served. Where LNK_MEMORY_NOTES names the notes,
the line serves them too, as large as the spec's notes, else 4096
bytes, with remember among the allowed calls.
Build and test
From the repository root:
cargo build -p link-memory-tool
cargo test -p link-memory-tool
cargo test -p link-memory-tool --test memory index::Its tests
tests/agent.rs drives it through Link's own lnk agent memory start,
tests/reads_conversations.rs reads a conversation folder as Link
Harness keeps one, and tests/notes.rs writes the notes.
PDF and Word text
PDF and Word text comes from Link Document Converter (lnk-document-converter), a
module of its own that memory runs as a child, with no secrets and with
its own resource limits, answering as its
contract says; memory's build compiles no document parser
(why).
Its command prints programs: ["document-converter"], so its sandbox reads
that program where it's installed.
What a model sees
Each answer's content is its JSON, fenced as third-party text. Its
structuredContent is the same answer without what the documents say:
a search's titles and snippets, a list's titles, and a document's links'
titles and targets are in the fenced text alone, so a client that gives
its model the structured content never shows them bare. A read keeps
its read receipt there but not its text or title, and a reader checks
the receipt against the text of the fenced JSON.
Text Read Receipts
A document read includes a read receipt identifying its source snapshot
and selected byte span. Its text digest describes the returned lines,
after line-ending normalization. Lossy UTF-8 decoding is recorded as a
separate transformation and never credited as complete content. A requested
line count or missing continuation alone does not establish whole-source
coverage. The harness separately records any limit on delivery to its model.
Many agents, one process
lnk-memory-tool serve-many serves every agent of one owner on the
machine, a session per connection, each answered from its own agent's
index alone.
Its limits
Each of memory's own limits is in src/limits.toml, read once into
Limits (src/limits.rs) and checked by the_limits_read: the largest
file indexed (1 MiB), the most documents links gives each way, the
most removed documents remembered, and the document converter's time
and memory. What a call may ask for, the most results and tokens, is
its declaration's maximum in actions.toml, read from the calls it
renders, so it's never typed twice.
Session limits
A session's message is at most 1 MiB: past it, that session ends. At most 256 sessions are served at once, and one more is refused, saying so. A compact conversation's frames are read to 64 MiB, newest first, and decoded only to 4 MiB by each frame's declared size, so a file an agent wrote can't take the shared service's memory.
Opening each index
Each agent's index is opened at its first session, under a lock of its own, so one agent slow to open holds up no other, and two sessions arriving at once open it once.
Its embeddings
A search's words are embedded before the agent's index is reached, so a model slow to answer holds up no other session of the agent. A model already served for it is used from the first search; one memory starts itself is found in the background, and searches are by words until then.
Kept off the folder
Where an agent's machine keeps what memory reads off its folder (its
conversations, its notes or its memory, in SQLite, a bucket or a box's
store, as ~/.lnk/safe/agents/policy.toml's [storage] says), or its Home in a bucket
on a machine that runs agents only while they answer, the session's
first line binds the agent (link_memory_tool_contract's Hello with
Bound): its owner, its key for this start, and its bridges. The
service then serves it by owner and ID, as no other owner's agent of
the same ID.
Binding an agent
On a computer, lnk agent memory connect binds it so, with the key
this machine's keyring holds, and lnk agent memory service runs the
service with --bridges <its folder>/bridges.
On a machine that runs agents only while they answer
Its service binds each agent as it wakes, running lnk-memory-tool serve-many <socket> --cache <folder> --stay --peer <its user> --socket-group <a group of both> --files-bridge <socket> --storage-bridge <socket>, its
socket shared with --socket-group (mode 660) in a folder no one else enters.
Tree
What memory indexes is behind one seam (src/tree.rs's Tree):
a folder on the machine (Folder), with its conversations through the
storage bridge where they're kept elsewhere, or Home through the files
bridge and conversations through the storage bridge (Bridged), each
call proved as the agent.
Listing a bridged tree
A bridged tree is listed when the agent is bound, and two seconds after
the files bridge says something under memory/ changed
(Control::Changed), never on every call. A skill's file, never
indexed, is read by its path from either (Tree::read_unindexed), when
read finds nothing indexed there.
Notes kept elsewhere
remember writes its notes through the storage bridge where its
memory collection is kept elsewhere (notes.rs's Notes::stored), each a
write that names the version it read.
A team's memory, bound
A session whose Hello names a team besides its binding is the
agent's session of that team's memory (service/bridges.rs), by the
team's ID: the team's folder's memory/ through the files bridge as
the agent (InTeam), its index's copy beside the folder, cached at
<folder>/<owner>/<agent ID>/teams/<team ID>/. The bridge serves the
team's index only to a member granted all of the folder, so a member
granted part of it is refused at bind; only one writing all of it
(writes) writes the index back.
A member that keeps no index
A session without writes or semantic embeds nothing: it
searches the copy beside the folder, and what changed there since, by
their words alone, never by meaning, since a search's meaning is a call
to the embedding model too.
Paid team queries
semantic opts readers into the team's embeddings. A team proof appends
:<team ID>:<files-bridge name> to the binding header and binds both
values into its HMAC challenge. The endpoint resolves current membership,
folder access, opt-in and payer outside the engine, before each paid
attempt. The engine supplies neither payer nor spending allowance.
Ended with its agent
It writes no notes and reads no conversations. The agent's Flush
writes its teams' indexes back with its own, and its End ends them; a
Changed naming the team lists that folder again.
The index as a cache
The index is then a cache, mode 0600 (<folder>/<owner>/<agent ID>/
for an agent the service isn't named, else its own index file), of a
copy (memory/src/cache.rs): kept with the agent's memory collection
where that's elsewhere (memory/link-memory/, through the storage
bridge), else beside Home where Home is in a bucket.
Its segments
The file is cut into 8 MiB segments named by their SHA-256, and a manifest naming them, written last and only if it's still the version the cache was read from.
Fetching the copy
A cache with no copy fetches it, each segment checked against its hash.
The copy is the owner's to change, so it's then checked whole (SQLite's
quick_check) and for memory's own schema alone (no table, index,
trigger or view of its own), and one that fails, or misses a segment,
is made again and written back. Every index is opened in SQLite's
defensive mode with its schema untrusted.
The machine's own bridges
The bridges a binding names must be the machine's own
(--files-bridge, --storage-bridge, or the agent's own
<folder>/<agent>/storage.sock in --bridges <folder>), else it's
refused before its key goes anywhere. A binding is served, even from a
cache already there, only once one of them takes its key, and a cache
is used only while it's of the copy there now.
Writing it back
A changed index is written back at most once a minute, and at
Control::Flush, which the machine sends before the agent sleeps,
after embedding what's waiting for up to 20 seconds. A write back
refused for its version drops the cache, fetches the copy again and
indexes what it lacks.
Control::End
Control::End drops the agent's key, and a session still open answers
nothing more; its cache stays, for the machine to remove. Every control
names the agent by owner and ID.
Its model's address
serve --embed <model> reaches its model at --embed-url, which falls
back to LNK_MEMORY_MODEL, the variable the engine protocol gives an
engine its served model's address in. Each address means one thing:
- A URL: the model is served there, outside the sandbox.
- Empty: a model was served for it, but no runtime here has it, so it searches by words.
- Left out: it serves the model itself, with
lnk model serve.
serve-many reads each agent's serve line with that agent's own
environment from the agents file, never its own process's, so each
agent's address is its own (link_actions::cli::under).
An embedding server for many owners
It's given as --embed-url unix:<path>, an OpenAI-style
/v1/embeddings on a Unix socket, each bound request carrying
Authorization: Link-Binding <agent>:<proof>. A bound endpoint must be
Unix: no binding credential is sent over HTTP.
The proof
The proof is HMAC-SHA256 of memory embedding binding and the
binding's identity, made with its existing key
(link_memory_tool_contract::embedding). A shared engine proves each agent
separately. The proof lasts only for that binding and is held as a
redacted secret.
The owner
The server resolves the owner from its Unix peer and the current binding; memory sends no owner header.
tests/home.rs
It runs all of the bridged memory against a stand-in files bridge over
an encrypted folder, and against a storage bridge over lnk-sqlite-store.