Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Current product update — 9 November 2026. App Chat is an implemented, optional App Shell feature with its own published configuration and permission-scoped source/action bindings. It does not use generic Agent Memory entries as a substitute for source authorization, conversation ownership or lineage. References below to “planned App Chat” describe the historical design, not current product availability. See the current App Chat lesson. This note does not claim a particular app has been runtime-verified.

Agent Memory

Choose the memory boundary deliberately

Generic memory stores facts, preferences, summaries and tool records. Decide the authorized source, intended subject, useful lifetime and admitted readers before writing content. Its scope string narrows searches; it is not a private owner/workspace boundary. A private Ask Inflow conversation uses the distinct owned conversation/memory service described in Studio Agent.

Contract Practical meaning
scope / subjectId Caller-supplied grouping and subject, not issued access proof.
ttlSeconds A positive value produces expiresAt from the service clock.
kinds / query / limit Narrow the intended search; default50, maximum500.
includeExpired An explicit diagnostic choice, not a retention bypass.
deactivate Marks inactive; does not establish physical erasure or audit deletion.

The following cases use only fictional leave data. They describe storage/search behavior without asserting a model run, privacy certification or actual deployment test.

Example UIAI-AGENT_MEMORY-01 — Store a short-lived case fact

Scenario and inputs. An extension already admitted its caller and the fictional request leave-2026-014. It wants to remember five requested working days while preparing a nonconfidential demonstration. It has AGENT_MEMORY_WRITE and deliberately chooses one hour of usefulness.

Procedure. Send the actual WriteAgentMemoryCommand fields to /api/agent-memory. Choose a real enum kind and meaningful scope/subject values. Retain the generated ID, creation/expiration timestamps and active state from the response. The caller attribution in this body is descriptive input, not independent authentication evidence.

{
  "scope":"workspace:people-ops:leave-demo",
  "agentId":"agent.case.worker",
  "memoryPolicyId":"demo-short-lived",
  "subjectId":"leave-2026-014",
  "kind":"FACT",
  "content":"The fictional request covers five working days.",
  "attributes":{"requestedDays":5},
  "createdBy":"REPLACE_WITH_ADMITTED_CALLER_ID",
  "ttlSeconds":3600
}

Expected result. A positive TTL computes expiresAt and an active record receives a generated memory ID. This fact does not approve leave, execute a rule or give another consumer access to the underlying business record.

Failure and recovery. Correct invalid admitted input rather than guessing a stored ID. Private or provider-restricted source content must follow its domain's actual storage/disclosure policy. Copying it into a generic store does not remove that policy; keep demonstration content synthetic while implementing the integration.

Sources. Memory controller, write fields, expiration creation.

Example UIAI-AGENT_MEMORY-02 — Search the intended subject and understand expiry

Scenario and inputs. The extension retained its own grouping scope and subject leave-2026-014. Its admitted purpose needs these synthetic FACT records, not every subject or expired value. AGENT_MEMORY_VIEW is required independently of the filters.

Procedure. Search with explicit scope, subjectId, kinds, query, includeExpired:false and a small limit. Add agentId or memoryPolicyId when they further narrow the purpose. Inspect the returned subject, active state and expiry instead of assuming the first match is current business truth.

{
  "scope":"workspace:people-ops:leave-demo",
  "subjectId":"leave-2026-014",
  "query":"five working days",
  "kinds":["FACT"],
  "includeExpired":false,
  "limit":10
}

Expected result. Normal repository searches exclude inactive/expired records. The default request limit is fifty and its maximum is five hundred; choosing ten makes this exercise's bounded purpose clear. Empty matches are a successful search with no qualifying rows, not an authentication or dependency failure.

Failure and recovery. Inspect whether an absent fact expired, was deactivated, used another subject, or failed to write. Include expired values only under an admitted diagnostic purpose. Removing filters cannot repair a denial and must not be described as a way to discover other people's conversation history.

Sources. Search request, repository search, expiry test.

Example UIAI-AGENT_MEMORY-03 — Deactivate the exact returned record

Scenario and inputs. The demonstration fact is no longer useful. Its owner retained the generated memory ID and has the native deletion permission for that operation. The subject ID is not the memory ID, and no audit record or another owner's evidence is included in this exercise.

Procedure. Read /api/agent-memory/{memoryId}, verify the intended subject, then DELETE that exact route. Inspect the returned active state and repeat the original narrow normal search. Explain to a user that this deletion-shaped route implements deactivation, rather than claiming that every physical or historical copy was erased.

Expected result. The stored record becomes inactive and ordinary active searches stop returning it. The repository and any audit/history remain subject to their own retention contracts. This distinction is important when documenting memory lifecycle behavior or planning compliance evidence.

Failure and recovery. A missing ID is an error, not permission to substitute a guessed value. A denied deletion stays denied. After an uncertain response, reconcile the same known record's active state before any repeat. Do not clear an entire scope or remove retained evidence to make a demonstration start from a convenient empty store.

Sources. Deactivate route, service operation, deactivation test.

Example UIAI-AGENT_MEMORY-04 — Recognize a private-history requirement

Scenario and inputs. Sara must reopen her own assistant conversation without Mohammad receiving that history merely by editing a client field. This is a concrete ownership requirement. Generic memory exposes caller-chosen scope, subject and createdBy fields, so a clever prefix cannot satisfy it alone.

Procedure. Inspect the controller/service path before choosing storage. The ID route checks its generic memory permission and delegates the lookup; it does not derive an owner filter from scope. Search preserves empty filters as valid request defaults. For the existing Studio surface, use its actual server-owned conversation service and approved memory lifecycle. A future app-specific chat needs its own admitted context and authorization boundary.

Expected result. The design records the difference between grouping and access control. A guarded integration may still store admitted content here, but cannot claim this generic API independently provides per-user privacy, current source authorization, source lineage or model-disclosure approval.

Failure and recovery. If an existing integration assumed prefixes enforced isolation, keep private content out of this demonstration and raise the gap to its domain owner. Do not demonstrate cross-user reads, borrow credentials or change access code as part of writing a manual. Document the limitation and use the actually supported alternative.

Sources. Generic ID/search routes, generic delegation, owned conversation service.

Current source reference. The worked examples are source-reviewed documentation; live execution is NOT_RUN.

Agent memory is the durable context store for AI and agent execution. It lets agents save facts, summaries, decisions, tool results, user input, and audit notes so later runs can reuse controlled context instead of starting from zero every time.

Architecture

flowchart LR
    client["API client or worker"] --> controller["AgentMemoryController"]
    controller --> guard["AccessGuard"]
    controller --> service["AgentMemoryService"]
    service --> repo["AgentMemoryRepository"]
    repo --> jdbc["JdbcAgentMemoryRepository"]
    jdbc --> db[("agent_memory table")]

The service contract is adapter-oriented. Platform code depends on AgentMemoryService and AgentMemoryRepository; the application assembly uses JdbcAgentMemoryRepository, while an in-memory adapter remains available for focused tests. The original table was introduced by migration 000016_create_agent_memory; later migrations may extend its operational context, so the ordered migration set is the schema source of truth.

Memory Record

Each record stores:

  • scope: caller-supplied grouping and search key, usually named for a tenant, workspace, process, or case.
  • agentId: optional agent owner.
  • memoryPolicyId: policy copied from the agent catalog.
  • subjectId: optional business subject such as document id, case id, customer id, or process instance id.
  • kind: FACT, PREFERENCE, SUMMARY, DECISION, TOOL_RESULT, USER_INPUT, SYSTEM_NOTE, ERROR, or AUDIT.
  • content: human-readable memory text.
  • attributes: extensible JSON metadata.
  • sourceRunId: optional originating agent run.
  • createdBy, createdAt, expiresAt, active.

REST API

All endpoints are authenticated by the same platform security chain as the rest of the services.

Write Memory

POST /api/agent-memory

Required permission: AGENT_MEMORY_WRITE.

{
  "scope": "tenant:acme",
  "agentId": "agent.document.reviewer",
  "memoryPolicyId": "agent-memory-document-scoped",
  "subjectId": "DOC-7",
  "kind": "SUMMARY",
  "content": "Document DOC-7 requires legal and finance approval.",
  "attributes": {
    "confidence": 0.91
  },
  "sourceRunId": "run-7",
  "createdBy": "worker-1",
  "ttlSeconds": 3600
}

ttlSeconds is optional. Use 0 or omit it for non-expiring memory.

Search Memory

POST /api/agent-memory/search

Required permission: AGENT_MEMORY_VIEW.

{
  "scope": "tenant:acme",
  "agentId": "agent.document.reviewer",
  "memoryPolicyId": "agent-memory-document-scoped",
  "subjectId": "DOC-7",
  "query": "finance approval",
  "kinds": ["SUMMARY"],
  "includeExpired": false,
  "limit": 10
}

Search currently supports structured filters plus case-insensitive text matching over content. The interface is intentionally stable so a later semantic/vector adapter can be added without changing callers.

Read Memory

GET /api/agent-memory/{memoryId}

Required permission: AGENT_MEMORY_VIEW.

Deactivate Memory

DELETE /api/agent-memory/{memoryId}

Required permission: AGENT_MEMORY_DELETE.

Deletion is a soft deactivation (active = false). This keeps auditability while removing the record from normal search results.

Permissions

This generic memory API checks the listed platform permissions. Its scope, agentId, subjectId, createdBy and memoryPolicyId fields are supplied by the caller; they are not server-issued proof of user, workspace or source access. An ID read does not add a scope filter, and a search without a scope does not establish one automatically. Do not use a chosen scope string as a security boundary or describe this store as private conversation history. A consumer that needs business-object isolation, current source authorization, retention enforcement or AI-disclosure checks must obtain those guarantees through its own admitted domain boundary before storing or reusing content.

The Studio Agent's owned conversations are a separate contract with server-bound ownership and workspace checks. Planned App Chat is not implemented by assigning generic memory entries an app prefix.

The default development roles grant:

  • admin: all permissions through *.
  • designer: AGENT_MEMORY_VIEW, AGENT_MEMORY_WRITE.
  • worker: AGENT_MEMORY_VIEW, AGENT_MEMORY_WRITE.

Memory deletion is admin-only by default.

Extension Points

To add another storage engine, implement AgentMemoryRepository and wire it as the Spring bean:

public final class MyAgentMemoryRepository implements AgentMemoryRepository {
    // save, findById, search, deactivate
}

To add semantic retrieval later, keep the API shape and replace or decorate search(...) with embeddings, vector stores, ranking, or policy-based retrieval.

BPMN Service Tasks

The service task catalog includes executable memory tasks:

  • service.agent.memory.write
  • service.agent.memory.search

These are handled by AgentMemoryServiceTaskExecutor.

Write From A Workflow

Configuration can provide one content value or a facts object/list.

{
  "scope": "tenant:acme",
  "agentId": "agent.document.reviewer",
  "memoryPolicyId": "agent-memory-document-scoped",
  "subjectId": "DOC-7",
  "kind": "FACT",
  "facts": {
    "approval": "Finance approval is required.",
    "deadline": "Signature deadline is July 15."
  },
  "sourceRunId": "run-7",
  "ttlSeconds": 86400
}

Output contains memoryIds, memories, and memoryCount.

Search From A Workflow

{
  "query": "finance approval",
  "filters": {
    "scope": "tenant:acme",
    "subjectId": "DOC-7",
    "kind": "FACT"
  },
  "topK": 5
}

Output contains matches and matchCount.

Operational Notes

  • Always set a meaningful scope for grouping and bounded search; it does not grant or enforce access by itself.
  • Use subjectId for case/document/customer/process-level memory.
  • Use memoryPolicyId from the agent catalog to make retention and retrieval policy auditable.
  • Use TTLs for temporary tool results and long-lived records only for facts, decisions, and preferences that should survive future runs.

Try “document generation”, “integrations” or “first form”.