Skip to main content
AtomicMemory provides two paths for writing memories from a conversation. The full ingest endpoint runs LLM-based fact extraction and applies the AUDN-SC mutation algorithm (Add, Update, Delete, No-op, Supersede, Clarify) to keep your memory store consistent over time. The quick ingest endpoint skips extraction entirely and stores the raw content after an embedding-based deduplication check — trading accuracy for throughput.

​
POST /v1/memories/ingest

Full ingest processes the conversation messages through the memory engine: facts and claims are extracted, compared against existing memories in the specified scope, and mutated according to the AUDN-SC decision logic. Contradictions are detected and resolved automatically. This is the recommended path for durable facts, stated preferences, and decisions you want to persist reliably.

​
Request

POST /v1/memories/ingest
​
messages
array
required
The conversation messages to extract memories from. Each element is a message object with the following fields:
​
scope
object
required
The scope to store the extracted memories in. At least one of the following keys must be present:
​
completion
string
The final assistant response text, if it is not already included as the last message in the messages array. Providing it here lets you pass the raw messages array from your model call without modification.

​
Example Request

curl -X POST http://127.0.0.1:17350/v1/memories/ingest \
  -H "Authorization: Bearer local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I prefer TypeScript over JavaScript."},
      {"role": "assistant", "content": "Noted, I will use TypeScript in my examples."}
    ],
    "scope": {"user": "alice"}
  }'

​
Response

​
ingested
number
The number of new memory records created in this operation.
​
updated
number
The number of existing memory records updated due to new or changed information.
​
deleted
number
The number of memory records deleted because the new content explicitly invalidates them.
​
noop
number
The number of extracted claims that matched existing memories exactly and required no change.
​
memories
array
An array of memory objects affected by this ingest call.

​
Example Response

{
  "ingested": 1,
  "updated": 0,
  "deleted": 0,
  "noop": 0,
  "memories": [
    {
      "id": "mem_abc123",
      "content": "Alice prefers TypeScript over JavaScript.",
      "action": "add",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

​
POST /v1/memories/ingest/quick

Quick ingest stores content directly after running an embedding-based near-duplicate check. No LLM extraction occurs — the content you provide is stored as-is if it is sufficiently different from existing memories in scope. This makes it significantly faster and cheaper than full ingest, at the cost of extraction accuracy and AUDN-SC mutation logic.

​
Request

The request body is identical to /v1/memories/ingest. The same messages, scope, and optional completion fields apply.

​
Example Request

curl -X POST http://127.0.0.1:17350/v1/memories/ingest/quick \
  -H "Authorization: Bearer local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Meeting at 3pm on Friday with the design team."}
    ],
    "scope": {"user": "alice", "thread": "thread_xyz"}
  }'

​
Response

​
ingested
number
1 if a new memory record was created, 0 if the content was a near-duplicate and was skipped.
​
skipped
number
1 if the content was detected as a near-duplicate of an existing memory and was not stored, 0 otherwise.

​
Example Response

{ "ingested": 1, "skipped": 0 }
Use full ingest (/v1/memories/ingest) for durable facts, user preferences, and decisions where accuracy and contradiction detection matter. Use quick ingest (/v1/memories/ingest/quick) for high-throughput pipelines, ephemeral notes, or situations where you want fast writes and can tolerate occasional duplicates slipping through at low similarity thresholds.