Skip to content
ALTAIRA LABS
DocsBlog
OmniaOmnia

Curate institutional knowledge

Add operator-authored facts, such as policies or approved terminology, to a workspace’s institutional memory tier.

Prerequisites

Section titled “Prerequisites”
  • Enterprise enabled. Without it the institutional routes return 403 with enterprise_required.
  • The URL of the workspace’s memory-api, exported here as MEMORY_API. If internalServiceAuth.enabled is set, add a ServiceAccount bearer token as described in Authentication and scope.
  • The Workspace UID. workspace_id and the workspace query parameter must be a UUID, and a workspace name is rejected with a 400.
Terminal window
export WORKSPACE_ID=$(kubectl get workspace <workspace> -o jsonpath='{.metadata.uid}')

Add a memory

Section titled “Add a memory”

  1. Post the memory. The metadata keys about_kind and about_key are optional.

    Terminal window
    curl -fsS -X POST "$MEMORY_API/api/v1/institutional/memories" \
      -H 'Content-Type: application/json' \
      -d '{
        "workspace_id": "'"$WORKSPACE_ID"'",
        "type": "policy",
        "content": "Customers may return unused items within 30 days of delivery.",
        "confidence": 1.0,
        "metadata": {
          "about_kind": "policy",
          "about_key": "returns"
        },
        "expires_at": "2027-01-01T00:00:00Z"
      }'

    The endpoint writes at workspace scope with curated provenance and takes no user or agent scope. expires_at is optional and must be in the future.

  2. If the bound MemoryPolicy declares a schema, set type to a type declared there that allows the institutional tier. See How the schema is enforced.

  3. To change a memory later, post again with the same about_kind and about_key. The new observation supersedes the previous one instead of creating a duplicate. Without both keys, every post creates a new memory.

The response returns the stored memory with 201. It can also include embedding_backlog, the number of memories waiting to be embedded. Semantic recall misses a new memory until the re-embed worker, which runs hourly by default, has embedded it.

Add memories from the dashboard

Section titled “Add memories from the dashboard”

Open Memories in the sidebar and select Workspace knowledge. The page lives at /workspaces/<workspace>/knowledge.

  • Under “Add knowledge”, enter a Type and Content, then select Add. This form sends no confidence, metadata or expires_at.
  • Select Bulk import to paste a JSON array of {type, content} objects, optionally with confidence, metadata and expires_at, or Markdown.
  • In Markdown, each ## heading starts one memory. The heading becomes the type, lowercased and hyphenated, and the text below it becomes the content. Markdown import carries no confidence or expiry.

Remove a memory

Section titled “Remove a memory”

Delete by memory ID. The workspace parameter is required.

Terminal window
curl -fsS -X DELETE "$MEMORY_API/api/v1/institutional/memories/<id>?workspace=$WORKSPACE_ID"

The memory is soft-deleted and leaves the list. A memory ID that belongs to a user or agent returns 400.

Make a memory expire

Section titled “Make a memory expire”

An expires_at ages a memory out only when the institutional tier’s retention mode is TTL or Composite. The default mode, Manual, never removes expired institutional memories. Set tiers.institutional.mode in the MemoryPolicy to change it.

Verify

Section titled “Verify”

List the tier.

Terminal window
curl -fsS "$MEMORY_API/api/v1/institutional/memories?workspace=$WORKSPACE_ID"

The response is {"memories": [...], "total": N}. The new memory appears in memories. limit and offset page the list.

Troubleshooting

Section titled “Troubleshooting”

The post returns 400 workspace_id must be a UUID

Section titled “The post returns 400 workspace_id must be a UUID”

Send the Workspace UID, not its name.

The post returns 400 about the memory schema

Section titled “The post returns 400 about the memory schema”

The type is not declared in the bound MemoryPolicy’s schema, or the type does not allow the institutional tier. Use a type that the schema lists for that tier.

The post returns 403 enterprise_required

Section titled “The post returns 403 enterprise_required”

Enable Enterprise on the install.

Section titled “Related pages”