Semantic memory

An agent that works out how your tests run, which service owns a table, or why a migration has to ship first, loses all of it when its run ends. The next run starts from zero and works it out again.

With memory, agents keep what they learn. A run proposes a lesson, Ryph checks it before it goes in, and every later run starts with the memories that fit its task. Runs then confirm what still holds and correct what doesn’t, so memory keeps up with your code.

What a memory is

A memory is one claim, at most 500 characters, such as “Migrations in api/ must merge before the code that uses them.” Each one has:

• A subject: your whole organization, or one repository.
• A kind: a fact, a procedure, a gotcha, a decision, a preference, or a pointer to a document.
• Where it came from: a person, a document, or an agent’s run. A person can pin a memory, so every run gets it.
• Its track record: how many runs confirmed it and refuted it, and how many briefs it’s been in.

How a run uses memory

• It starts with a brief. Before the agent starts, Ryph picks the memories that fit the task, its repositories and its agent. It ranks them by how relevant they are, how much they’re trusted, how often runs confirmed them and how recent that was, and fills the agent’s brief budget, 2,000 tokens by default. Pinned memories are always in it. The brief is fixed when the run starts.
• It looks things up as it works. The agent can search memory in plain words, read a memory or a whole document, and propose, confirm or refute memories.
• It’s warned when code moved. A memory about a repository can name the commit and files it’s based on. Before the agent starts, Ryph checks whether those files changed since. If they did, the prompt marks the memory as possibly outdated, and it stays out of later briefs until a run confirms it again.

Search by meaning, on your own hardware

Agents rarely ask in the words a memory was written in. A run that wonders “how do I run the tests?” should find “Tests are vitest; run them with deno task test,” which shares none of its words. So Ryph searches memory by meaning, with an embedding model that runs inside Ryph.

• It runs where Ryph runs. The model is bge-small-en-v1.5, a small open model that ships inside the ryph binary and Ryph’s memory image. It runs in the memory service itself, so memories don’t go to an embedding API, and there’s no key to manage or bill to pay.
• Every memory is ready to find. Ryph turns each memory into a vector as it comes in, and fills in the ones from before in the background.
• Words and meaning both count. A search ranks each memory by the better of how well its words match and how close its meaning is, so exact names and commands still come first when they’re there.
• No vector database. The vectors live in Ryph’s own Postgres, next to the memories, so there’s nothing extra to run.

It’s on in the ryph binary and in every Compose and Kubernetes setup Ryph ships, and adds about 270 MB of memory to the memory service. RYPH_MEMORY_EMBEDDINGS=off turns it off, and search then matches words alone. If the model can’t load, the binary says so once and searches by words, while a separate memory service stops at startup and says why.

How a lesson gets in

Agents don’t write memory themselves. What they propose goes into an inbox, and Ryph decides what comes out of it:

• It waits for the run’s change to land, when it depends on one. A claim the run found already true is checked right away. A claim that’s true only because of the run’s own change, like a new test command, waits until that change merges. If the pull request is closed, the claim goes with it.
• It’s screened. A claim that holds a credential is refused. One that reads like instructions to agents waits for a person.
• It’s compared with what memory already says. A claim that repeats a memory confirms it. One that contradicts a memory replaces it, and the old one is retired with a link to the new. One that adds nothing is rejected, with the reason. What’s left is rewritten as one clear claim, and moved to the organization if it’s about more than one repository. This step uses the background model.

Most proposals go through on their own. Those held for a person wait in the Inbox tab on the Memory page, where operators and owners can Accept, Edit and accept or Reject them, one at a time or in bulk.

How memory stays accurate

• Runs report back. When a memory helped, the agent confirms it. When it was wrong, the agent refutes it with a corrected claim, which goes through the inbox like any proposal.
• One run can’t retire a memory alone. A refutation takes the memory out of briefs until a run confirms it again. Refutations from two different runs, with no confirmation between them, retire it.
• Old memories fade. Each kind of memory ages at its own pace. One that runs stop confirming ranks lower over time, and one that’s faded far enough without being used is retired.

Each memory’s page lists every confirmation, refutation and brief it was part of, and everything people did to it.

Teach it yourself

Write memories by hand. On the Memory page, Write a memory adds one straight to memory, with Pin it, so it’s always in the brief for the ones every run should know. Operators and owners can edit, pin and retire any memory.

Hand it documents. Under Sources, Ingest a document takes pasted text, a Markdown or text file, a URL, or a file from a public GitHub or GitLab repository. Ryph splits it into sections and turns them into proposals, which you accept or reject together. It also adds a pointer, so agents can read the whole document when they need more.

• A new version replaces the old. Ingest an updated runbook, and what the new one no longer says is retired, while what both say is confirmed.
• A mistake can be undone. Move puts a document and its memories under the right subject. Withdraw rejects what’s still waiting, retires what it added, and removes the document, apart from memories someone pinned.

Ryph doesn’t clone private repositories for memory. Paste or upload their documents, or let agents propose what they find in them.

Turn it on for an agent

Open Agents, pick the agent, click Edit and go to Tools and memory. Turn on Enable memory for this agent, and set the Brief budget (tokens) if 2,000 doesn’t fit.

Under Advanced, Scope memories to this agent only gives the agent its own memory. Its runs see only memories meant for that agent, and what it proposes stays with it. Shared memories, pinned ones included, and other agents’ memories are left out. People with access to memory still see all of them.

What memory needs

• A background model compares proposals with memory, rewrites them and turns documents into proposals. Pick one under Platform, in Background model, and its calls go through the model proxy. Without one, Ryph still screens proposals and folds exact repeats together, but adds the rest as written, and documents produce no proposals.
• Search by meaning comes from the embedding model, described above. It’s on in every deployment Ryph ships, with nothing to set up.

Health, on the Memory page, shows how this deployment’s memory is doing: what’s live, what needs verifying, what has never been in a brief, and what it has to work with.

How the brief is ranked and how memories age is in Shared memory.