Skip to main content
Ingestion methods create new memory records or update existing ones. All five methods return an IngestResponse containing the JSON-encoded MemoryRecord that was written to the store.
​
record
bytes
JSON-encoded MemoryRecord. Decode the bytes field to access the record’s id, type, sensitivity, salience, and payload.

​
IngestEvent

Creates an episodic memory record from a raw event. Use this to capture user inputs, errors, agent actions, or any discrete occurrence that should be preserved for later consolidation.

​
Request fields

​
source
string
required
Identifies the actor or system that produced the event (e.g., "build-agent").
​
event_kind
string
required
Categorises the event (e.g., "tool_call", "user_input", "error").
​
ref
string
required
Reference identifier for the source event, used in provenance tracking (e.g., "build#42").
​
summary
string
Human-readable summary stored in the episodic timeline. Maximum 100 000 characters.
​
timestamp
string
RFC 3339 timestamp. Defaults to the server’s current UTC time when omitted.
​
tags
string[]
Free-form labels for categorisation. Maximum 100 tags, each up to 256 characters.
​
scope
string
Visibility scope (e.g., "project-acme", "user", "global").
​
sensitivity
string
Sensitivity classification: public, low, medium, high, or hyper. Defaults to the server’s configured default_sensitivity.

​
Example

rec, err := m.IngestEvent(ctx, ingestion.IngestEventRequest{
    Source:    "build-agent",
    EventKind: "tool_call",
    Ref:       "build#42",
    Summary:   "Executed go build, failed with linker error",
    Tags:      []string{"build", "error"},
})
fmt.Printf("Ingested episodic record: %s\n", rec.ID)

​
IngestToolOutput

Creates an episodic memory record that captures a tool invocation with its arguments and result. The tool data is stored in the episodic payload’s tool_graph field alongside a timeline entry.

​
Request fields

​
source
string
required
Identifies the actor or system that invoked the tool.
​
tool_name
string
required
Name of the tool that was called (e.g., "bash", "read_file").
​
args
bytes
JSON-encoded map[string]any of arguments passed to the tool. Maximum 10 MB.
​
result
bytes
JSON-encoded value returned by the tool. Maximum 10 MB.
​
depends_on
string[]
IDs of tool nodes this output depends on, used to build the tool dependency graph.
​
timestamp
string
RFC 3339 timestamp. Defaults to the server’s current UTC time when omitted.
​
tags
string[]
Free-form labels for categorisation.
​
scope
string
Visibility scope.
​
sensitivity
string
Sensitivity classification: public, low, medium, high, or hyper.

​
Example

rec, err := m.IngestToolOutput(ctx, ingestion.IngestToolOutputRequest{
    Source:   "build-agent",
    ToolName: "bash",
    Args:     map[string]any{"command": "go build ./..."},
    Result:   map[string]any{"exit_code": 1, "stderr": "linker error: cannot find -lfoo"},
    Tags:     []string{"build", "error"},
})

​
IngestObservation

Creates a semantic memory record from a subject-predicate-object triple. Use this to record stable facts and preferences that should persist and be retrievable across sessions.

​
Request fields

​
source
string
required
Identifies the actor or system making the observation.
​
subject
string
required
The entity the observation is about (e.g., "user", "project").
​
predicate
string
required
The relationship or property observed (e.g., "prefers_language", "has_deadline").
​
object
bytes
required
JSON-encoded value or related entity (e.g., "\"go\""). Maximum 10 MB.
​
timestamp
string
RFC 3339 timestamp. Defaults to the server’s current UTC time when omitted.
​
tags
string[]
Free-form labels for categorisation.
​
scope
string
Visibility scope.
​
sensitivity
string
Sensitivity classification: public, low, medium, high, or hyper.

​
Example

rec, err := m.IngestObservation(ctx, ingestion.IngestObservationRequest{
    Source:    "build-agent",
    Subject:   "user",
    Predicate: "prefers_language",
    Object:    "go",
    Tags:      []string{"preferences"},
})

​
IngestOutcome

Updates an existing episodic record with an outcome status. The target record must be episodic — attempting to attach an outcome to a non-episodic record returns FailedPrecondition. The update appends a provenance source and an audit entry to the target record without changing its type or payload structure.
IngestOutcome modifies an existing record. It does not create a new one. The response contains the updated record.

​
Request fields

​
source
string
required
Identifies the actor or system reporting the outcome.
​
target_record_id
string
required
ID of the existing episodic record to update.
​
outcome_status
string
required
Result of the experience: success, failure, or partial.
​
timestamp
string
RFC 3339 timestamp. Defaults to the server’s current UTC time when omitted.

​
Example

updatedRec, err := m.IngestOutcome(ctx, ingestion.IngestOutcomeRequest{
    Source:         "build-agent",
    TargetRecordID: rec.ID,
    OutcomeStatus:  schema.OutcomeStatusSuccess,
})

​
IngestWorkingState

Creates a working memory record that captures in-flight task state. Working memory records enable task resumption across sessions or devices.

​
Request fields

​
source
string
required
Identifies the actor or system that produced the working state.
​
thread_id
string
required
Identifier for the current thread or session (e.g., "session-001").
​
state
string
required
Current task state: planning, executing, blocked, waiting, or done.
​
next_actions
string[]
Ordered list of planned next actions.
​
open_questions
string[]
Unresolved questions blocking or affecting the task.
​
context_summary
string
Human-readable summary of the current context. Maximum 100 000 characters.
​
active_constraints
bytes
JSON-encoded array of Constraint objects currently active for the task. Maximum 10 MB.
​
timestamp
string
RFC 3339 timestamp. Defaults to the server’s current UTC time when omitted.
​
tags
string[]
Free-form labels for categorisation.
​
scope
string
Visibility scope.
​
sensitivity
string
Sensitivity classification: public, low, medium, high, or hyper.

​
Example

rec, err := m.IngestWorkingState(ctx, ingestion.IngestWorkingStateRequest{
    Source:     "build-agent",
    ThreadID:   "session-001",
    State:      schema.TaskStateExecuting,
    NextActions: []string{"run tests", "deploy"},
})

Build docs developers (and LLMs) love

Get started for freeTalk to us