Skip to main content

Add app knowledge

Use the knowledge surface when an app needs business facts, FAQs, policies, or other source material that its AI can retrieve. The surface reuses TWL Tool's Memory package and presents it as a non-technical knowledge workspace.

Declare the surface​

import {defineApp} from '@twl-tool/app-sdk';

export default defineApp({
  key: 'ai-receptionist',
  name: 'AI Receptionist',
  version: '0.3.0',
  permissions: [
    'memory.read',
    'memory.write',
  ],
  ui: {
    defaultSurface: 'overview',
    surfaces: [
      {
        key: 'knowledge',
        label: 'Knowledge',
        type: 'knowledge',
        icon: 'book-open',
        description: 'What AI Receptionist knows about your business.',
        containerKey: 'business-knowledge',
        allowWrite: true,
      },
    ],
  },
});

The host turns containerKey into an installation-scoped Memory container. Two organizations installing the same app never share knowledge, and two installations in one organization remain separate.

Read-only and editable knowledge​

Request memory.read for a searchable, read-only knowledge surface. To let users add, edit, and remove facts, also request memory.write and set allowWrite: true.

The native surface provides:

  • categorized memories and source labels;
  • text search;
  • add, edit, and delete actions;
  • document and connector counts;
  • indexing health and recently learned facts;
  • a test-answer action that runs Memory retrieval against the same container.

Use the same knowledge in a workflow​

When an app workflow needs context, recall from the installation-scoped container rather than a global organization container. The Apps Layer supplies the installation and surface binding; the Memory package remains responsible for indexing, retrieval, and lifecycle management.

Keep the app's durable facts in Memory and its message history in a conversations surface. This lets an AI receptionist learn about the business without treating every inbound message as permanent knowledge.