Writing memory

When information comes up that should persist (a decision, a correction, a violation, an approved solution, an important file, a person's preference), you write it to memory. Agent Memory stores the text as is; it does not reinterpret it with an LLM at write time.

EndpointsCopy Anchor Link

ExampleCopy Anchor Link

curl -s -X POST $API/v1/memory/append \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: billing-decision-7' \
  -d "{
    \"workspaceId\": \"$WS\",
    \"runId\": \"billing-refactor-12\",
    \"layer\": \"Workspace\",
    \"type\": \"decision\",
    \"content\": \"Invoice numbers are generated with a year prefix, sequentially per tenant\",
    \"tags\": {\"facet\": \"billing\"},
    \"sourceKind\": \"agent\",
    \"sourceRef\": \"PR-482\"
  }"
# {"id":"…","merged":false,"contentReplaced":false,"operationId":"…"}

FieldsCopy Anchor Link

MCP add_memory accepts most of the same fields (content, type, runId, visibility, userId, facet, sourceKind, sourceRef, observedAt, validFrom, validTo, idempotencyKey) and additionally accepts supersedes: the new memory is written and the given old memory is immediately treated as superseded by it. MCP always writes to the Workspace layer.

ResponseCopy Anchor Link

Duplicates and mergingCopy Anchor Link

Every Workspace write is checked for duplicates within the same type and facet:

• Identical content within the last hour → no new memory is created; the existing memory's "mention" count increases.
• Semantically very close content, or content with high word overlap → merged into the existing memory; its evidence count and stability increase.
• Memories with a different visibility, owner, end user or application are never merged.

When every row must stay separate, such as in bulk imports, duplicate checking can be turned off in settings (dedup.enabled, see Configuration).

Safe retries: Idempotency-KeyCopy Anchor Link

To safely repeat the same request after a network error, send an Idempotency-Key header (1–128 characters). The same request with the same key within 24 hours returns the original response again (Idempotency-Replayed: true). Using the same key with a different body returns 409 IDEMPOTENCY_CONFLICT. The header also works on update, delete, share and consolidation calls. In MCP, use the idempotencyKey parameter.

Content safetyCopy Anchor Link

• Content that resembles prompt-injection patterns is quarantined: the memory is stored but does not appear in search or in reads by ID. Someone with the review permission (curate) can release or reject it with POST /v1/memory/{id}/review.
• If personal data is detected (pattern-based: email, delimited phone numbers, Luhn-validated card numbers, mod-97-validated IBANs, Turkish national ID numbers, US SSNs), the memory gets a pii tag. The memory is not rejected and the content is stored; it is not made a tenant-wide rule candidate, and the relevant parts are masked in exports and webhook summaries. This is not model-based DLP; it does not catch personal data outside these patterns.

Turning raw conversation text into memoryCopy Anchor Link

No extraction happens at write time. To extract information from conversation lines:

1. Write the lines with layer: "Session", type: "raw" under the same runId.
2. Call POST /v1/memory/consolidate; optionally steer what gets extracted with extractionInstructions.

curl -s -X POST $API/v1/memory/append -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"workspaceId\":\"$WS\",\"runId\":\"chat-301\",\"layer\":\"Session\",\"type\":\"raw\",
       \"sourceKind\":\"user\",\"content\":\"user: I want the reports as PDF every Monday, not Excel.\"}"

curl -s -X POST $API/v1/memory/consolidate -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"workspaceId\":\"$WS\",\"runId\":\"chat-301\",
       \"extractionInstructions\":\"Extract only reporting and communication preferences.\"}"
# {"status":"consolidated"}

If no LLM is configured, extraction is rule-based (the text is split into clauses; instructions are ignored). Details: Consolidation, episodes and procedures.

Recommended writing habitsCopy Anchor Link

• One memory = one piece of information. The form "We chose X because Y" works well for both search and contradiction detection.
• Choose the right type; consolidation, contradiction rules and procedure learning all work by type.
• If a piece of information replaces an older one, pass supersedes in MCP; don't expect the system to infer it from text similarity.
• Write person-specific information with userId, and notes that belong only to the agent itself with visibility: "private".

Related pagesCopy Anchor Link

• Search and context compilation
• Updating, superseding and deleting
• Identity and access