Write Memory

POST/agent/memory/write

Store a memory in the knowledge base. The memory pipeline automatically:

1. Classifies the memory type
2. Runs guard checks (conflict detection & quality scoring)
3. Extracts entities and relationships
4. Builds/updates the knowledge graph
5. Stores the vector embedding

Request

Headers

Header	Value
Authorization	Bearer sm_agent_...
Content-Type	application/json

Body Parameters

contentstringrequired

The memory content to store (1–50,000 characters).

volume_idstring (UUID)required

Target volume to write the memory into.

memory_typeenum

Optional. One of: factual, preference, event, relationship, technical, episodic, procedural. Auto-detected if omitted.

Response

200 Memory stored successfully

{
  "status": "approved",
  "reason": "New factual information about John Smith's role",
  "confidence": 0.92,
  "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent": "my-agent",
  "volume_id": "..."
}

Field	Description
status	approved — stored · rejected — blocked by guard · merged — merged with existing
reason	Human-readable explanation of the guard decision
confidence	0–1 confidence score from the guard
memory_id	UUID of the stored memory

Example

cURL

curl -X POST https://api.sharedmemory.ai/agent/memory/write \
  -H "Authorization: Bearer sm_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "John Smith is the CTO of Acme Corp. He joined in 2022.",
    "volume_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "memory_type": "factual"
  }'

TypeScript SDK

import { SharedMemory } from '@sharedmemory/sdk'

const memory = new SharedMemory({ apiKey: 'sm_agent_...' })

const result = await memory.remember(
  "John Smith is the CTO of Acme Corp. He joined in 2022.",
  { volumeId: 'a1b2c3d4-...', memoryType: 'factual' }
)

console.log(result.status)     // "approved"
console.log(result.confidence) // 0.92

Python

import requests

response = requests.post(
    "https://api.sharedmemory.ai/agent/memory/write",
    headers={"Authorization": "Bearer sm_agent_..."},
    json={
        "content": "John Smith is the CTO of Acme Corp. He joined in 2022.",
        "volume_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "memory_type": "factual"
    }
)

print(response.json())

Errors

Status	Error	Description
400	validation_failed	Invalid input — check details for field-level errors
403	agent_not_authorized_for_volume	Agent doesn't have write access to this volume
429	Too Many Requests	Rate limit exceeded (30/min)
500	write_failed	Internal error — retry with exponential backoff