How does an AI agent remember what it learned?

An agent finishes a ticket in which a certificate had expired. It renewed it, and the case is closed. In the done step it writes down what it learned: "Ticket 4711 of 29.07.2026: certificate expired."

Two weeks later the same problem comes back, and the agent starts from nothing.

The sentence is not wrong. As memory it is worthless, because it is about an incident rather than about a thing. What the agent looks for next time is certificate renewal — and nothing in its memory carries that name.

A page is a thing, not an incident

The agent's memory is therefore a wiki: linked Markdown pages, one per thing, searchable through a pgvector index. Not a transcript, and not a heap of text snippets. A thing is a customer, a project, a system, a person, a recurring problem or a topic, and the list ends there.

Those six are the whole vocabulary. PageTypes in internal/memory/memory.go closes it, and the comment next to it says why: on the kanban columns, freely invented labels proliferated within days until the structure meant nothing. Whatever does not fit becomes thema.

The rule the agent works to is one sentence long, and the wiki schema states it as well. A new page when it is a self-contained thing that can be referred to from elsewhere. Everything else is an attribute or an update of something that already has a page, and it goes there.

The links are the graph

In its prose a page points at other pages with [[wikilinks]]. extractLinks reads them out of the body and stores them beside the page as edges: customer, ticket, solution, the colleague in charge. That is the whole knowledge graph, with no graph store next to it and no pipeline extracting triples out of prose.

When a task is picked up, vector search returns the matching pages, optionally extended by one wikilink hop. That single hop runs over index.md and the links to the entities connected to a hit: customer, colleague in charge, their open topics. On top of that the agent sees the compact index of its entire wiki with title and slug, so it also knows what it does not know.

Search first, then one hop at most. The spec gives two reasons for that order. The vector index sits on top of the pages, so the agent no longer finds random snippets but the relevant pages. And the compact index shows it more than the top hits, so it navigates deliberately and creates duplicates less often.

The pages live twice, with the roles split

Those pages sit in the sandbox home as ~/wiki/<slug>.md next to an index.md. The agent reads and writes them with ordinary file tools and needs no interface of its own. The daemon materialises them there when a task starts and syncs the changes back when it ends.

The authoritative copy we keep in the control plane, in Postgres. Lose the sandbox and you lose no knowledge.

That serves a second purpose. With the manage role you can read a page, correct a single sentence in it or delete it; pages tended by hand carry source: manual and stay distinguishable from what the agent learned itself. A memory nobody can look into cannot be corrected either.

Six findings a wiki reports about itself

A page nobody links stays findable, and the quality bar counts it. It reports the page as an orphan, one with no live outgoing reference and none coming in. Next to that stand dead links, pages without a type, suspected duplicates and stubs, meaning pages with fewer than 120 characters of text.

A title counts as a diary entry from 80 characters upwards, or when it carries a date, and either one is enough. "Ticket 4711 of 29.07.2026: certificate expired" stays well under the length limit at 46 characters, and the bar reports it anyway because of the date.

Two places change something without the agent: the maintenance pass and the dream

The finding itself changes nothing. It is deliberately read-only and replaces no judgement; it shows where judgement is needed. A maintenance pass in the control plane merges pages from a similarity of 0.93 upwards, without a model and at no cost. At night the dream reads at most forty pages and decides which title names an event instead of a thing.

Afterwards it tells you which page it renamed, from what to what, and why. A rename you can undo one at a time. A merge you cannot — which sentence came from which page would be guesswork by then.

What this costs

This memory costs two things, and both belong to it.

The built-in embedding measures word overlap. "The pipeline is red" and "The CI build is failing" share no word, so their similarity is zero.

With that the assignment stops working: the agent does not find its own page again as soon as it phrases things differently. For production a real embedding therefore belongs in front of it, run yourself or bought as a service through COVEY_EMBEDDING_PROVIDER.

The second is discipline at writing time. If you file an insight through covey/remember as free-form prose, it is appended to the nearest page from a similarity of 0.80 upwards. Below that a new page appears, and its title is the first sentence, cut to 80 characters. That is how a diary entry appears that somebody has to clear up later.

An agent that simply files every sentence pushes that work onto the curation pass. Curation is what lets knowledge condense with every task instead of merely growing. A memory that only grows is an archive.