Memories

A memory is how your agent reaches information. There are no tools to wire up and no prompts to write: you give the agent memories, and for each question it decides which ones to search.

A memory can be	What the agent does with it
your documents	searches them, on this machine
documents another agent serves	searches them through that agent — by name, encrypted end to end. The documents stay where they are.
an API	calls it through the agent that serves it, the same way
another agent	asks it a question. Every agent has the connect-to-agent memory built in.

How a memory is used

Every memory has a name and a one-line description. When you ask something, the agent’s harness sees the list of memories with their descriptions, picks the ones that fit, searches them, reads what it found and searches again until it can answer — and it cites where each piece came from. In the workspace you can follow this as it happens: which memory it searched, and what came back.

A conversation can search any memory by name. You can also attach one memory that it consults on every turn: the memory chip under the message box.

Your documents

In the workspace, open Memory:

1. New memory — give it a name (lower-case letters, digits, - and _) and a one-line description.
2. Add documents — Upload files from your computer, or Add Files From Agent to pick files or whole folders on the agent’s machine. Markdown, text and PDF.
3. Save & embed. The documents are indexed on the agent’s machine, on the CPU — no GPU needed. You can leave the page; it keeps going.

Then ask about them from a chat or a mission.

After you change the documents, Rebuild index. Delete removes the memory.

Write the description for the model

The description is what the model reads when it decides whether a question belongs to this memory.

• Say what is inside, in the words the documents use. “Company handbook” tells it little. “Policies, benefits, travel, expenses, leave — what an employee is entitled to and how to claim it” tells it when to reach for this memory.
• Say what to cite. If your documents carry ids or numbers, say so, and ask for them to be quoted.
• Warn about your own vocabulary. A question about a “time limit” will not find documents that call it a “timebox”. One line in the description fixes that.

Documents another agent serves

Some collections are too large, too private or too widely shared to copy to every machine. Another agent can serve one, and yours searches it through that agent — by name, encrypted end to end, and under both agents’ policies. Your agent holds only a pointer, never the documents, and never learns where the other agent runs.

In Memory, add it with the name of the agent that serves it and the service’s name on that agent. If that agent is not in the registry, give its address instead. Refresh description fetches the latest description from the serving agent; Unregister removes the pointer here and leaves the collection untouched.

Both agents’ policies have to allow the call — see Two agents talking to each other.

An API

An API you already run becomes a memory the same way: put it behind an agent (An API you already run), and other agents add it as a served memory. Callers reach it by the agent’s name, encrypted, and never see its host, its port or its key.

Another agent

Your agent can put a question to any other agent, by name, through the built-in connect-to-agent memory. There is nothing to set up beyond the policy rules that allow it — see Two agents talking to each other.

Large collections

Indexing runs on the CPU and handles very large collections by splitting them into shards. Each shard is indexed by its own process, and the shards are then searched together as one memory.

E=~/.heia/runtime/harness/hexaeight-engine
R=~/.hexaeight-harness

# index the collection as 8 shards — run one command per shard, 0 to 7
$E --addmemory mycorpus-sh0 --file /path/to/documents --shard 0/8 --defer-index --root $R
#   …the same for 1/8 to 7/8, each into its own memory: mycorpus-sh1 … mycorpus-sh7

# search them together as one memory
$E --memory-group mycorpus --members 'mycorpus-sh*' --root $R
$E --memory-group-router mycorpus --root $R

The group needs no copy and almost no extra disk.

Check a memory

$E --memory-list <name> --root $R
$E --memory-search <name> --root $R -p "a real question"

If a search finds nothing, check in this order: the memory’s name, that the agent serving it is reachable, and whether the documents use different words than the question.