Project memory

Project memory is what carries across artifacts: knowledge tied to a realm, a subtree, a profile, or a class, rather than to one specific instance. It's the difference between "this page uses German weights" (artifact memory) and "Flowpad pages should always validate weights before save" (project memory at class scope).

The four wider scopes

Scope	Meaning	Lookup
`class`	tied to a class of artifact (`classRef` on the saved memory matches the query)	every actor of that class sees it
`subtree`	tied to a mount prefix	all descendants share it
`profile`	tied to a `profileKey` (cross-target)	every session under that profile sees it — used by `propose` and `edit`
`global`	unrestricted	admin-only

Plus realm — a free-form string column on every memory (memories.realm in schema.sql:31). Realm is not a scope; it's a tag that can be used in cascade lookups for cross-cutting groupings (e.g. "this memory applies to the entire HiveCast deployment").

When to use which

Class memory. Things true for any instance of a class. "Always sanitize HTML in chat.message content."
Subtree memory. Things true for a mount and its descendants. "Smithers and its constraint actors share this glossary."
Profile memory. Things true under a working mode. "When in propose profile, prefer focused tests over full-suite runs."
Global memory. Operator-level knowledge. "Always log retries through system.observability."
Realm. Cross-cutting tags. "This came from the v14 migration audit."

Saving project memory

bash

matrix invoke system.agents.memory memory.save '{
  "mount": "system.agents.system.flowpad",
  "content": "Always validate weights before saving a Flowpad page",
  "scope": "class",
  "tags": ["flowpad", "validation"],
  "realm": "platform-policy"
}'

Note that mount is the actor saving the memory, not the actor it applies to. The pinning is in targetKey (which we did not set — class scope is target-agnostic) and scope.

Retrieval

The cascade in searchMemoriesCascade (AgentsStore.ts:251-259) is "broadest scope wins." A query at scope actor includes memories saved at actor, class, subtree, and global. A query at scope instance includes everything from instance outward. So project memory naturally surfaces when an artifact-scoped lookup has nothing to say.

Audit and isolation

Project-scope memories are still audited in memory_access_log like any other read. Authority root is the hard tenant boundary — a memory in tenant A's database is invisible to tenant B's queries because the system.agents.memory is per-Host, per-authority-root.

What project memory is NOT

A wiki. It's not editable through a UI today; writes go through memory.save only.
A versioned knowledge base. Memories are append-only; there's no mutation. To "update" a fact, save a new memory and rely on created_at for recency.
An LLM-context auto-feed. Memories are pulled per turn by the active profile's memoryScope setting. A profile with memoryScope: 'none' will not see them at all.

Project memory ​

The four wider scopes ​

When to use which ​

Saving project memory ​

Retrieval ​

Audit and isolation ​

What project memory is NOT ​

See also ​