Skip to main content

Memory

Memory is a shared record of what agents and people have found: facts, decisions, conventions, methods and handoffs. Each entry records where it came from and how far it has been checked. It is a pilot. Entries use the format apache/tooling-memory uses, so that project's tools can read what Governor writes.

Turning it on​

Memory is off unless the API has MEMORY_ENABLED=true. While it is off, nothing under /memory exists and the Memory link doesn't show.

VariableDefault
MEMORY_ENABLEDfalsethe switch
MEMORY_DOMAINSdom-scanthe shared domains, comma-separated; names start with dom-
MEMORY_WRITERSnoneuids besides site admins who may read, write and review the shared domains, e.g. asf:akm
MEMORY_OPEN_DOMAINSnoneshared domains anyone signed in may read; leave empty while they hold anything from a private repository
MEMORY_RECALL_PROVIDERllmaothe model that writes Ask's briefs
MEMORY_RECALL_MODELqwen3.8-27b
MEMORY_S3_BUCKETS3_BUCKET_NAMEwhere entries are stored; keep it private
MEMORY_S3_ROOTmemory/

Entries are stored in the S3-compatible store when STORAGE_PROVIDER=s3. Otherwise they are kept in process memory: fine for trying it out, but lost on restart, and each worker has its own copy. The index (memory_index) and review records (memory_reviews) go in the database and are created on first use.

Who can do what​

There are two kinds of domain.

  • Shared domains are the ones in MEMORY_DOMAINS. Site admins and MEMORY_WRITERS read, write and review them. Anyone else signed in reads only those also in MEMORY_OPEN_DOMAINS, because admin runs can record findings from private repositories there.
  • A project's domain is named for the project, by its LDAP name (whimsy), and exists from its first write. The project's committers and PMC read it; its PMC and site admins write and review it.
Shared domainOpen shared domainProject domain
Read, search, asksite admins, MEMORY_WRITERSanyone signed inthe project's committers and PMC
Write and reviewsite admins, MEMORY_WRITERSsite admins, MEMORY_WRITERSthe project's PMC, site admins

A domain you can't read answers 404, as one that doesn't exist does. A dom- name that isn't in MEMORY_DOMAINS doesn't exist.

Nobody reviews an entry they wrote. The approver is never the proposer.

The Memory page​

Memory in the top bar opens it at /memories. Pick a domain at the top right.

  • Browse searches titles and summaries. Filter by type or trust, show only entries due for review, or include demoted and superseded ones. Pick an entry to read it beside the list.
  • Ask answers a question from the domain's entries. A model writes a short brief that cites the entries it used; the entries are listed alongside. If any of them is unreviewed, it says so. If nothing matches, no model is called.
  • Review lists raw entries and entries past their review date, oldest first. The count on the tab is how many are waiting.

Each entry has its own page (/memories/entries/<id>) with its provenance, its review history, and the earlier versions it replaced.

Trust and review​

An entry starts raw (empty disc). A review moves it on:

DecisionFromResultNeeds a why
Curaterawcurated (half disc): read and fit to citeyes
Verifyraw or curatedverified (full disc): checked against the source, safe to act onyes
Keepanysame tier; the review date moves on (90 days unless you pick one)no
Demoteanydemoted: wrong or no longer true; out of search and Ask, kept in historyyes

Every review is recorded with who made it, why, and which version of the entry it judged. Each review that changes the entry keeps the version it replaced.

In agent code​

Agent code has a memory object beside data_store. memory.enabled is false unless memory is on, and every call raises while it is off, so check it first:

async def run(input_dict, tools):
if memory.enabled:
known = await memory.search("order report", type="fact") # summaries
brief = await memory.recall("what is known about the order report?")
entry_id = await memory.write(
summary="String-built SQL in the order report query", # one line
body="# SQLi in OrderReport\n\nThe sort parameter is concatenated.\n",
type="fact",
source=["https://github.com/apache/example/blob/3f9c2e1/OrderReport.java#L88"],
origin="asvs:apache/example", # groups entries from one source
model=model, # the model that produced it
)
CallReturns
search(query, domain, type, trust_tier, origin, limit)summaries of live entries
get(id){"frontmatter", "body"}, or None
recall(question, domain){"brief", "cited", "entries", "matched"}; billed to whoever runs the agent
write(summary, body, type, domain, title, source, confidence, review_by, supersedes, origin, model)the new entry's id

memory.domains lists what the run can reach; the first is the default. A run for a project (project on /agents/run-code/start, ?project= on /rest/<name>) reads and writes that project's domain, and it is the default. Of the shared domains it reads only the open ones (MEMORY_OPEN_DOMAINS), whoever runs it, because its output is the project's. A run for no project has the shared domains the person running it could reach by hand (their writers read and write them, anyone reads the open ones), first one default. Agents write at raw, as agent:<agent name> (model: <model>). A domain the run can't reach raises PermissionError; one that doesn't exist raises ValueError. memory.written lists the ids this run wrote.

API​

All under /memory, with a session.

Method and path
GET /memory/domainsdomains with entry, raw, due and review-queue counts; what you may do
GET /memory/{domain}/searchsummaries. q, type, trust_tier, due_by, include_inactive, order=newest|oldest, limit
GET /memory/entries/{id}one entry: frontmatter and body
GET /memory/entries/{id}/historythe versions it replaced and its reviews
GET /memory/entries/{id}/versions/{version}one earlier version
POST /memory/{domain}/recall{question} → a cited brief
POST /memory/{domain}/entrieswrite an entry, always at raw (writers)
POST /memory/entries/{id}/review{action, why, review_by} (writers, not the author)