How to Use Cerebro in the ORIA Workbench

How to Use Institutional Memory in the ORIA Workbench#

Institutional Memory is ARPIA's persistent knowledge layer, powered by Cerebro. Inside an ORIA Workbench session it appears as a first-class panel section — not a tool you attach — and it is on by default.

The Workbench is the one place where institutional memory and structural authoring meet in the same session. Start with The Defaults Are the Design: the session's opening posture tells you more about how to work well than any list of rules.

For the Workbench itself, see How to Use the ORIA Workbench. For the read-first counterpart, see How to Use Institutional Memory in the ORIA Reasoner.

Where to find it. Right-hand panel, first section, labelled Institutional Memory with a badge showing how many domains you can access. The gear icon opens its settings; the power icon toggles it for the session. It sits above Repository, Ontology Nodes, Tools in this session, Artifacts and Files — it is not an entry inside Tools, and not an MCP collection you connect.

Overview#

What makes the Workbench different from the Reasoner: both read and write memory, through an identical settings panel. Only the Workbench can author structure.

The Defaults Are the Design#

A fresh Workbench session opens with a deliberate asymmetry, and the empty state says so: "I start with nothing enabled on purpose — reshaping a repository should be something you switched on for this session. Once it is on, every change still waits for you to approve a plan."

Read together: memory is opt-out, authoring is opt-in, and execution is gated twice — once by permission and once by your approval. The most consequential configuration — memory informing structural writes — cannot happen by accident. You select a writable repository, enable authoring, hold the apply permission, and approve a plan.

Knowing that shapes where your attention belongs. The approval prompt shows you what will change. It does not show you whether the reason for the change is sound. A plan reading "rename to contract_renewals per the naming convention" looks the same whether that convention is a recorded rule or an inference. Checking the reasoning happens before the plan, not at the prompt.

Why This Combination Matters#

The value: Oria can consult a prior decision — a naming convention, a modeling standard, a resolution from a past change — and apply it directly to the tables and nodes it authors. Your ontology stops drifting away from the decisions that shaped it.

Where care is needed: whatever memory says becomes the stated rationale for changes you're asked to approve. Verifying that rationale is the highest-value habit in this tool. See Working Well.

Prerequisites#

1. Institutional Memory is enabled for the work-area by an ARPIA admin.
2. Your user has at least read_only scope on the domains you'll query, and read_write on any domain you'll save to — or move a memory into.
3. ORIA Workbench itself is configured — a Model Group must be set, or the Workbench is disabled entirely. See Before You Start.
4. Your seat plan is Arpia Builder. Platform-level building, including ontology authoring and governance, is not available on Oria Basic or Oria Pro.
5. To author: a Repository must be selected (right panel → Repository → pencil icon). Everything you author lives there. Until one is chosen the panel reads "No repository selected." To create tables, that repository must be writable — check for the RW scope badge in the picker.
6. To author: switch on the tools you need from Tools in this session → Ontology Authoring — Author Tables (inspect and create tables) and Author Nodes & Relations (model them).
7. To apply ontology changes: your profile needs the Author-Apply permission. Without it, Oria can propose and you can review, but nothing commits.

Access is granted by an administrator. A user can be added to a domain, but removing access or changing an existing scope (read_only → read_write) is an administrative action. Grant deliberately.

The Institutional Memory Panel#

Expanding the section lists your in-scope domains as chips under a header reading All domains [n] — everything you have access to. The gear icon opens the settings dialog. This dialog is identical in the ORIA Reasoner, so the mental model transfers between the two tools.

1. Use institutional memory in this session#

Checked by default. Turn it off and Oria answers from your session data and the conversation only — no organizational grounding.

Turning it off is a legitimate tool, not a failure state. Use it when you want an unanchored second opinion: a modeling approach not shaped by prior decisions, or a check on whether general knowledge agrees with your institutional record. Just know which mode you were in when you quote the result.

2. Limit to these domains#

Empty by default (All my domains…), meaning Oria may read any domain you can access. Choose specific domains and it cannot read outside them. Organization-wide rules are included either way.

Narrowing scope is good practice: sharper answers, and less chance that unrelated or work-in-progress content shapes the response. If your organization keeps sandbox or test domains, they are in scope by default — worth excluding when the answer matters.

3. Ask me before saving anything#

Unchecked by default. The consent model is asymmetric:

Nothing is written to a shared domain without a prompt. Personal memory accumulates without one unless you opt in.

Turn it on if you audit your own memory, work in a regulated or evidentiary context, or simply want every write to be a decision you made rather than one you allowed. The cost is a click per save. The benefit matters because memory has a 15-day edit window — after that a record can only be retired, not corrected.

Conceptual Model#

There are no default domains. Every domain is created by your organization. The names used on this page — acme_product, acme_security, acme_docs — are illustrative only. The two names that are product concepts rather than organizational choices are global (organization-wide immutable rules) and personal.

Organization                       ← tenant boundary; isolation is per-tenant
   └── Domain (acme_security, acme_docs, global, ...)
          └── Memory (mid_xxxxxxxx)
                 ├── knowledge_type_id  (from your organization's types)
                 ├── parent_mid          (causal antecedent)
                 ├── references[]        (external links with a role)
                 ├── expires_at          (optional expiration)
                 └── status              (APPROVED | INACTIVE)

Knowledge types#

The types below are typical. The authoritative set for your organization is whatever cerebro_init returns in available_types — don't assume a type exists until you see it there.

Reference roles#

Unlike knowledge types, the role on a reference is a fixed, closed set:

Any other value is rejected. source in particular is a common guess and is not valid — use context or quoted.

The Six Tools#

The panel is the interface; these are the mechanics underneath it. You won't normally call them by hand, but knowing what each does explains the behavior you see.

cerebro_init — discovery#

Runs once at the start of a session that touches organizational context. Returns the authenticated user, organization_id, organization_name, available_types, the accessible domain list, last_saved_memories, and global_immutable_knowledge.

{ "action": "initalize" }

The response informs later calls silently — it isn't printed unless you ask. Worth asking for once: the global immutable rules it surfaces are the constraints your organization has already decided are non-negotiable, and reading them often changes the question you were about to ask.

Init runs once per conversation, with one exception: re-run it after a successful cerebro_config.

cerebro_load — broad context#

For opening work on a known scope: "I'm extending the billing ontology," "let's continue the ERP migration model." domain is an array.

// Mode 1 — semantic retrieval within a scope (default)
{ "query": "question or topic", "domain": ["acme_product", "global"] }

// Mode 2 — specific memory by ID
{ "mid": "mid_a1b2c3d4" }

// Mode 3 — latest memories in a domain
{ "domain": ["acme_docs", "global"] }

// Mode 4 — inventory (metadata only, no content)
{ "mode": "list", "domain": ["acme_docs", "global"] }

list mode is the most useful and most overlooked. Use it for domain onboarding, for duplicate detection before any save, and as a safe default when it isn't clear whether Load or Search applies.

cerebro_search — specific answer#

For a pointed question institutional knowledge could answer: decisions, rules, standards, prior resolutions.

// Scoped to domains
{ "query": "natural-language question", "domain": ["acme_compliance", "global"] }

// All accessible domains plus global rules
{ "query": "natural-language question" }

search returns a synthesized answer plus an attribution block listing the contributing memories and their external references. That block is presented as-is, never paraphrased or trimmed — it is what makes the answer verifiable. If a search returns nothing, that is stated explicitly rather than filled in from general knowledge.

Load vs. Search#

In one line: Load answers "give me everything for this scope." Search answers "answer this question."

cerebro_save — create#

Creates only, never edits. A payload containing a mid is rejected and routed to cerebro_update.

Reactive only. Memory is written when you say "save," "remember," or "persist." Finishing an authoring task does not by itself write a memory.

{
  "title": "Memory title",
  "knowledge_type_id": "Procedure",
  "content": "Content...",
  "domain": "acme_product",
  "parent_mid": "mid_XXXXX",
  "references": [
    { "url": "https://docs.arpia.ai/...", "title": "Original doc", "role": "context" }
  ],
  "expires_at": "2026-12-31 00:00:00"
}

title, knowledge_type_id, content and domain are required.

domain is a single string here — not an array. Load and Search take arrays; Save takes one domain. If knowledge belongs in several domains, issue several saves.

Don't save when: nothing identifiable was decided or discovered; it's a personal preference (this is organizational knowledge, not user configuration); or a near-duplicate may exist — run load mode:"list" first, and if it's already there, what you want is an edit.

Content fidelity: if a draft was shown to you before saving, the saved title and content are character-identical to that text. No re-summarizing at save time — otherwise you approved one thing and the record says another.

Continuations are new saves. An addition to an existing memory is a new memory, optionally linked via parent_mid.

parent_mid guidance

Link only the primary, canonical antecedent:

Omit it when the relationship is loose ("related to," "same topic") or when several parents would apply — mention it in the body text instead. When in doubt, omit: it's cleaner to add a link later than to un-link a wrong one.

cerebro_update — correction#

Edits an existing record in place. Never creates. Requires a mid. If you don't have one, find it via search or load and confirm it's the right record before updating.

Reactive only — called when you explicitly ask to change, fix, correct, relink, re-domain, expire, or deactivate a memory. Recording something new, even a continuation, is a save.

Editable fields: title, content, domain, knowledge_type_id, references, expires_at, parent_mid, status. At least one must be present. Partial updates send only what changes; omitted fields are untouched.

// Content only (most common)
{ "mid": "mid_XXXX", "content": "Corrected content." }

// Move domain — requires read_write on the TARGET domain
{ "mid": "mid_XXXX", "domain": "acme_engineering" }

// Set an expiration
{ "mid": "mid_XXXX", "expires_at": "2026-12-31 00:00:00" }

// Clear an expiration — empty string, not null
{ "mid": "mid_XXXX", "expires_at": "" }

// Detach parent (becomes a root memory) — empty string, not null
{ "mid": "mid_XXXX", "parent_mid": "" }

// Retire a memory
{ "mid": "mid_XXXX", "status": "INACTIVE" }

Three semantics worth memorizing:

1. Clearing vs. changing. For expires_at and parent_mid, "" is an explicit clear; omitting the field leaves it as-is. Use the empty string, not null.
2. References are replaced, not merged. Sending references overwrites the whole list — to add one, resend the existing entries too. An empty array is rejected, so references cannot be cleared this way.
3. status accepts only APPROVED or INACTIVE.

The response reports updated_fields. Fields that weren't part of the edit report unchanged.

Edit window: 15 days from creation. Re-parenting does not extend it. Past the window the record is frozen — the remaining path is to mark it INACTIVE and carry the correction forward as a new save, parent_mid-linked to the record it replaces.

cerebro_config — domain structure#

// Create a domain
{ "action": "create_domain", "domain_slug": "slug_code", "domain_name": "Name" }

// Grant a user access
{ "action": "add_user_domain", "domain": "domain name",
  "user": "username", "scope": "read_only | read_write" }

• domain_slug: lowercase, underscores, no spaces or special characters. "Acme customer notes" → acme_customers.
• add_user_domain matches the domain by name, not by slug.
• The caller must already hold read_write on that domain.
• Grants only. Revoking access or changing an existing scope is an administrative action.

After every successful config, cerebro_init runs again. A new or renamed domain, or newly granted access, won't appear in Load, Save, or the panel's domain list until the session context refreshes.

On rename, prior saves and external tools referencing the old slug will need updating.

Working Well with Memory + Authoring Tools#

In a read-only session, memory shapes an answer. In a Workbench session with authoring enabled, memory shapes a plan you'll be asked to approve. A few habits make the difference.

1. Check the reasoning before the plan, not at the approval prompt#

Any numeric value, identifier, or naming decision Oria cites from memory is worth verifying against its source memory (load by mid) before it becomes the rationale for a structural change. Prefer search when attribution matters — only search returns the contributing-memories block.

The approval prompt shows you what will change. It doesn't show you whether the stated reason is grounded.

2. Scope domains deliberately#

Default scope is every domain you can access. Narrow it to what the question actually needs, and exclude sandbox or work-in-progress domains when the answer will inform a structural change.

3. Leave authoring off until you need it#

The session already defaults this way; the discipline is not enabling it out of habit. If you're exploring what memory says, you don't need a repository selected or authoring switched on. The read paths are equally available in the ORIA Reasoner, which cannot author structures at all.

4. Read the plan's justification, not just its diff#

The plan gate is a real control — use it as one. Ask why each change is proposed. If the answer cites a rule, a convention, or a prior decision, that citation is the thing to check. A correct-looking change built on a misremembered convention will apply cleanly and still be wrong.

5. Use the propose/apply split as a review step#

Author Nodes & Relations lets anyone who enables it propose ontology changes; applying them requires the Author-Apply permission. That gap is a control, not just a restriction.

It supports a two-person pattern: a modeller without Author-Apply drafts the change and its memory-based justification, and a second person with the permission reviews both before committing. The proposer checks what is changing; the approver checks why. For regulated or high-blast-radius work, that separation is worth arranging deliberately rather than granting Author-Apply to everyone who models.

6. Get the save right the first time#

The edit window is 15 days. Before saving: run load mode:"list" to rule out a duplicate, confirm the domain and knowledge type against init, and check the content against what was shown to you.

7. Memory is not approval#

Memory records that a decision was made. It doesn't make one. The in-session plan gate is a technical control, not a governance one — structural changes still go through your normal change-management process. Automating the execution of a change does not remove the need to authorize it.

Common Pitfalls#

Confident specifics#

Language models learn institutional structure accurately and can then state specific details — identifiers, metrics, dates — with the same confidence whether they were retrieved or inferred. In an authoring session, that confidence arrives as the justification for a plan.

The habit that addresses it: for anything specific, open the source memory rather than accepting the synthesis.

Approving the diff, not the reason#

The plan gate can create a false sense of completeness — every change was reviewed, so nothing slipped through. But reviewing what changes isn't reviewing why. That's the gap §1 exists to close.

Author-Apply granted by default to everyone who models#

The propose/apply split only functions as a review step if the two roles are actually held by different people. Granting Author-Apply alongside authoring access by default collapses four gates into three and removes the one that involves a second pair of eyes.

Sandbox content in scope#

Test and working domains sit in the default scope alongside authoritative ones, and a confident answer grounded in throwaway content looks exactly like a confident answer grounded in a decision. Narrow the scope, and expire or retire test domains you're finished with.

Memory written outside authoring sessions#

Memory writes aren't confined to the Workbench. In the ORIA Reasoner, institutional memory is on by default, shared-domain saves prompt, and personal-domain saves don't unless the user opts in. If your governance model assumes memory only changes during authoring, revisit that assumption.

Retired memories that were never retired#

Renaming a memory's title to mark it stale does not remove it from retrieval. Only expires_at or status: INACTIVE does.

Typical Workflow#

1. Open or resume an ORIA Workbench session. Institutional Memory is already on.
2. Open the panel. Set the domain scope and decide whether you want save prompts.
3. Review the global immutable rules — does any apply to today's authoring work?
4. load the relevant domain context, or search for the specific decision or standard you need.
5. Verify any cited identifier or figure against its source memory.
6. Select a Repository — everything you author lives there. Confirm the RW badge if you'll be creating tables.
7. Add the Ontology Nodes you intend to edit, then switch on the authoring tools you need.
8. Author the tables and nodes. Review each plan's justification before approving.
9. Validate by querying the resulting structure.
10. If a durable decision came out of the session, say so explicitly — then it's saved, with parent_mid pointing at its antecedent.

Leverage Points#

Small habits with disproportionate effect on system quality:

1. expires_at hygiene. The only automatic decay mechanism. Without it, signal degrades as volume grows. Apply it by default to anything operational with a known useful life.
2. mode:"list" before every save. Marginal cost; prevents the duplication behind most contradictory answers.
3. parent_mid discipline. Turns a flat set of memories into a navigable causal graph where every decision inherits its history. It's what separates memory from archive.
4. Keep the attribution. It's simultaneously the audit trail and the check on confident specifics. Trimming it for brevity loses both.
5. Retire, don't accumulate. status: INACTIVE is the only corrective action that still works on a frozen record.
6. Ask "why" at every plan gate. The habit that turns an existing technical control into a real check on reasoning.
7. Separate propose from apply. Author-Apply is the only gate in the chain that can involve a second person. Deciding who holds it is a governance choice, not an access-request formality.

Known Limitations#

• 15-day edit window. Past 15 days from creation a memory is frozen; re-parenting doesn't extend it. The remaining path is INACTIVE plus a corrected new save.
• Access changes require an administrator. Domain access can be granted in-session, but removing access or changing an existing scope cannot.
• References cannot be cleared. On update the list is fully replaced, and an empty array is rejected.
• The role enum is closed. Only context, quoted, discovery, and contradicted are accepted; other values are rejected at runtime.
• Renaming a title doesn't retire a memory. Only expiration or INACTIVE removes it from retrieval.
• The plan gate confirms the change, not the reasoning. It shows what will change, not whether the stated reason is grounded.
• Applying ontology changes requires the Author-Apply permission. Without it, memory-informed plans can be drafted and reviewed but not committed.
• Table creation requires a writable repository. A read-only repository allows inspection but not DDL.
• Requires admin setup and an Arpia Builder seat. The Workbench is disabled until a Model Group is configured at the work-area level; Institutional Memory requires separate work-area enablement; platform-level building requires the Arpia Builder plan.