Memories

Memory CRUD + retrieval (streaming) + file upload + batch ops.

Namespace: Goodmem.Client.Api · Class: MemoriesApi

Reach this surface as client.Memories on a GoodmemClient. Every network method is asynchronous — it returns a Task<T> (or an IAsyncEnumerable<T> for pagination and streaming) and accepts a CancellationToken; the Async suffix marks the standard .NET Task-based async pattern.

Methods

CreateAsync

Create a memory from text content or base64-encoded binary content. Content must be provided via exactly one of originalContent or originalContentB64. When using originalContentB64, contentType is required (the server cannot infer MIME type from base64 bytes). originalContentRef is a metadata pointer (URL) attached to the memory; it does NOT supply content and may accompany originalContent/originalContentB64.

Declaration

public Task<Memory> CreateAsync(JsonMemoryCreationRequest request, CancellationToken ct = default)

HTTP — POST /v1/memories

Parameters

Returns

Task<Memory> — an awaitable that resolves to Memory.

Exceptions

Examples

Example 1:

var memory = await client.Memories.CreateAsync(
    new JsonMemoryCreationRequest
    {
        SpaceId = "your-space-id",
        OriginalContent = "GoodMem stores and retrieves vectorized memories for RAG.",
        ContentType = "text/plain",
        Metadata = new Dictionary<string, object> { ["source"] = "sdk-doc-test" },
    }
);
Console.WriteLine(memory.MemoryId);

Example 2:

// Send base64-encoded bytes; contentType is required so the server knows the MIME type.
var b64 = Convert.ToBase64String(
    Encoding.UTF8.GetBytes("Base64-encoded memory content.")
);
var memory = await client.Memories.CreateAsync(
    new JsonMemoryCreationRequest
    {
        SpaceId = "your-space-id",
        OriginalContentB64 = b64,
        ContentType = "text/plain",
    }
);
Console.WriteLine(memory.MemoryId);

Example 3:

// Upload a file directly: the SDK reads it and sends a multipart request, inferring
// the content type from the file extension.
var memory = await client.Memories.CreateFromFileAsync(
    "your-space-id",
    "example.txt"
);
Console.WriteLine(memory.MemoryId);

CreateFromFileAsync

Create a memory from text content or base64-encoded binary content. Content must be provided via exactly one of originalContent or originalContentB64. When using originalContentB64, contentType is required (the server cannot infer MIME type from base64 bytes). originalContentRef is a metadata pointer (URL) attached to the memory; it does NOT supply content and may accompany originalContent/originalContentB64.

File overload: reads filePath from disk (memory-create uploads it as a multipart file part; OCR base64-encodes it into the JSON body) — the content type is inferred from the extension.

Declaration

public Task<Memory> CreateFromFileAsync(string spaceId, string filePath, JsonMemoryCreationRequest? request = null, CancellationToken ct = default)

HTTP — POST /v1/memories

Parameters

Returns

Task<Memory> — an awaitable that resolves to Memory.

Exceptions

Example

var result = await client.Memories.CreateFromFileAsync("your-space-id", "/path/to/document.pdf", new JsonMemoryCreationRequest { SpaceId = "your-space-id", ContentType = "..." });

RetrieveAsync

Performs a streaming semantic search across one or more memory spaces and returns matching chunks ranked by relevance as well as LLM-postprocessed results (like summarization, question-answering, etc.).

Declaration

public IAsyncEnumerable<RetrieveMemoryEvent> RetrieveAsync(string message, RetrieveOptions? options = null, CancellationToken ct = default)

HTTP — POST /v1/memories:retrieve

Parameters

Returns

IAsyncEnumerable<RetrieveMemoryEvent> — an async stream; await foreach yields each RetrieveMemoryEvent across pages / events.

Exceptions

Examples

Example 1:

await foreach (
    var ev in client.Memories.RetrieveAsync(
        "What is GoodMem?",
        new RetrieveOptions { SpaceIds = new[] { "your-space-id" }, RequestedSize = 5 }
    )
)
{
    // Each event is one kind of result; a retrieved chunk carries the ranked text.
    if (ev.RetrievedItem?.Chunk is { } chunk)
        Console.WriteLine($"score={chunk.RelevanceScore:F3}");
}

Example 2:

// RetrieveRawAsync takes a fully-formed request for advanced control.
await foreach (
    var ev in client.Memories.RetrieveRawAsync(
        new RetrieveMemoryRequest
        {
            Message = "What is GoodMem?",
            SpaceKeys = new[] { new SpaceKey { SpaceId = "your-space-id" } },
            RequestedSize = 5,
        }
    )
)
{
    if (ev.AbstractReply is { } reply)
        Console.WriteLine(reply.Text);
}

RetrieveRawAsync

Performs a streaming semantic search across one or more memory spaces and returns matching chunks ranked by relevance as well as LLM-postprocessed results (like summarization, question-answering, etc.).

Lower-level variant: takes a fully-formed request and returns the raw stream without the flat-parameter convenience layer. Use the non-Raw form for the ergonomic call shape.

Declaration

public IAsyncEnumerable<RetrieveMemoryEvent> RetrieveRawAsync(RetrieveMemoryRequest request, CancellationToken ct = default)

HTTP — POST /v1/memories:retrieve

Parameters

Returns

IAsyncEnumerable<RetrieveMemoryEvent> — an async stream; await foreach yields each RetrieveMemoryEvent across pages / events.

Exceptions

Example

await foreach (var item in client.Memories.RetrieveRawAsync(new RetrieveMemoryRequest { Message = "...", SpaceKeys = default! }))
{
    // handle each streamed event
}

GetAsync

Retrieves a single memory by its ID. PERMISSION CLARIFICATION: With READ_MEMORY_OWN permission, access is granted if you own the parent space OR if the parent space is public (public_read=true). With READ_MEMORY_ANY permission, you can access any memory regardless of ownership. This is a read-only operation with no side effects and is safe to retry. Returns NOT_FOUND if the memory or its parent space does not exist.

Declaration

public Task<Memory> GetAsync(string id, MemoriesGetOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/memories/{id}

Parameters

Returns

Task<Memory> — an awaitable that resolves to Memory.

Exceptions

Example

var memory = await client.Memories.GetAsync("your-memory-id");
Console.WriteLine(memory.ProcessingStatus);

ContentAsync

Returns the original binary payload for a memory. The response uses the memory's stored content type when available. Returns 404 when the memory does not have inline content; clients can check originalContentRef from the metadata endpoint to locate external content.

Declaration

public Task<byte[]> ContentAsync(string id, CancellationToken ct = default)

HTTP — GET /v1/memories/{id}/content

Parameters

Returns

Task<byte[]> — an awaitable that resolves to byte[].

Exceptions

Example

var content = await client.Memories.ContentAsync("your-memory-id");
Console.WriteLine($"{content.Length} bytes");

PagesAsync

Lists extracted page-image metadata for a memory with optional filters and pagination.

Declaration

public IAsyncEnumerable<MemoryPageImage> PagesAsync(string id, MemoriesPagesOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/memories/{id}/pages

Parameters

Returns

IAsyncEnumerable<MemoryPageImage> — an async stream; await foreach yields each MemoryPageImage across pages / events.

Exceptions

Example

// Auto-paginate page-image metadata for a memory.
await foreach (var pageImage in client.Memories.PagesAsync("your-memory-id"))
    Console.WriteLine(pageImage.PageIndex);

PagesImageAsync

Downloads inline bytes for one page image. The page index is required. The optional dpi and content type query parameters act as rendition filters; if omitted, the server returns the unique rendition for that page or rejects ambiguous matches.

Declaration

public Task<byte[]> PagesImageAsync(string id, string pageIndex, MemoriesPagesImageOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/memories/{id}/pages/{pageIndex}/image

Parameters

Returns

Task<byte[]> — an awaitable that resolves to byte[].

Exceptions

Example

var imageBytes = await client.Memories.PagesImageAsync("your-memory-id", "0");
Console.WriteLine($"{imageBytes.Length} bytes");

ListAsync

Lists memories within a given space. Results are paginated; pass the response's nextToken back as a query parameter to fetch subsequent pages.

Declaration

public IAsyncEnumerable<Memory> ListAsync(string spaceId, MemoriesListOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/spaces/{spaceId}/memories

Parameters

Returns

IAsyncEnumerable<Memory> — an async stream; await foreach yields each Memory across pages / events.

Exceptions

Examples

Example 1:

await foreach (var memory in client.Memories.ListAsync("your-space-id"))
    Console.WriteLine($"{memory.MemoryId} {memory.ProcessingStatus}");

Example 2:

// Resume from a pagination token you saved from an earlier page.
var savedToken = "your-saved-token";
await foreach (
    var memory in client.Memories.ListAsync(
        "your-space-id",
        new MemoriesListOptions { NextToken = savedToken }
    )
)
    Console.WriteLine(memory.MemoryId);

DeleteAsync

Permanently deletes a memory and its associated chunks. This operation cannot be undone and immediately removes the memory record from the database. IDEMPOTENCY: This operation is safe to retry - may return NOT_FOUND if the memory was already deleted or never existed. Requires DELETE_MEMORY_OWN permission for memories in spaces you own (or DELETE_MEMORY_ANY for admin users to delete any memory). Side effects include permanent removal of the memory record and all associated chunk data.

Declaration

public Task DeleteAsync(string id, CancellationToken ct = default)

HTTP — DELETE /v1/memories/{id}

Parameters

Returns

Task — completes when the operation finishes; there is no response body.

Exceptions

Example

await client.Memories.DeleteAsync("your-memory-id");

BatchCreateAsync

Create multiple memories in a single batch. Each item in requests follows the same per-call shape as memories.create: provide exactly one of originalContent or originalContentB64; originalContentB64 requires contentType (auto-inferred to text/plain for plain-text originalContent); originalContentRef is a metadata pointer that may accompany the content source. Per-item failures are reported individually and do NOT abort the batch.

Declaration

public Task<BatchMemoryResponse> BatchCreateAsync(JsonBatchMemoryCreationRequest request, CancellationToken ct = default)

HTTP — POST /v1/memories:batchCreate

Parameters

Returns

Task<BatchMemoryResponse> — an awaitable that resolves to BatchMemoryResponse.

Exceptions

Example

var result = await client.Memories.BatchCreateAsync(
    new JsonBatchMemoryCreationRequest
    {
        Requests = new[]
        {
            new JsonMemoryCreationRequest
            {
                SpaceId = "your-space-id",
                OriginalContent = "Batch memory one.",
                ContentType = "text/plain",
            },
            new JsonMemoryCreationRequest
            {
                SpaceId = "your-space-id",
                OriginalContent = "Batch memory two.",
                ContentType = "text/plain",
            },
        },
    }
);
foreach (var r in result.Results)
    if (r.Memory is not null)
        Console.WriteLine(r.Memory.MemoryId);

BatchGetAsync

Retrieves multiple memories in a single operation, with individual success/failure results.

Declaration

public Task<BatchMemoryResponse> BatchGetAsync(BatchMemoryRetrievalRequest request, CancellationToken ct = default)

HTTP — POST /v1/memories:batchGet

Parameters

Returns

Task<BatchMemoryResponse> — an awaitable that resolves to BatchMemoryResponse.

Exceptions

Example

var result = await client.Memories.BatchGetAsync(
    new BatchMemoryRetrievalRequest { MemoryIds = new[] { "your-batch-memory-id" } }
);
foreach (var r in result.Results)
    if (r.Memory is not null)
        Console.WriteLine(r.Memory.ProcessingStatus);

BatchDeleteAsync

Deletes memories using selector entries. Each selector can target either a specific memory ID or a filtered subset scoped to a specific space.

Declaration

public Task<BatchMemoryResponse> BatchDeleteAsync(BatchMemoryDeletionRequest request, CancellationToken ct = default)

HTTP — POST /v1/memories:batchDelete

Parameters

Returns

Task<BatchMemoryResponse> — an awaitable that resolves to BatchMemoryResponse.

Exceptions

Example

var result = await client.Memories.BatchDeleteAsync(
    new BatchMemoryDeletionRequest
    {
        Requests = new[]
        {
            new BatchDeleteMemorySelectorRequest { MemoryId = "your-batch-memory-id" },
        },
    }
);
Console.WriteLine(result.TotalDeleted);

CreateFromStreamAsync

Declaration

public Task<Memory> CreateFromStreamAsync(string spaceId, Stream content, string fileName, JsonMemoryCreationRequest? request = null, CancellationToken ct = default)

Parameters

Returns

Task<Memory> — an awaitable that resolves to Memory.

Exceptions

Example

var result = await client.Memories.CreateFromStreamAsync("your-space-id", File.OpenRead("/path/to/document.pdf"), "document.pdf", new JsonMemoryCreationRequest { SpaceId = "your-space-id", ContentType = "..." });

Data Models

Types in the Goodmem.Client.Models namespace. Each row lists the C# property, its type, the JSON wire name, and a description.

JsonBatchMemoryCreationRequest

Request body for creating multiple memories via application/json.

JsonMemoryCreationRequest

Request body for creating a new Memory. A Memory represents content stored in a space.

BatchMemoryResponse

Response containing per-item results for a batch memories operation

BatchMemoryResult

Individual item result for a batch memories operation

Memory

Memory object containing stored content and metadata

ErrorDetail

Structured error details for an individual batch operation result

ProcessingHistory

Background job execution history associated with a memory

BackgroundJobSummary

Summary of the most recent background job execution for a resource

BackgroundJobAttempt

Telemetry captured for a single execution attempt of a background job

BatchMemoryDeletionRequest

Request body for deleting memories using ID and/or filtered selectors

BatchDeleteMemorySelectorRequest

A single delete selector: either memoryId or filterSelector

FilteredDeleteMemorySelectorRequest

Filtered selector scoped to a specific space

BatchMemoryRetrievalRequest

Request body for retrieving multiple memories by their IDs

MemoryListResponse

Response containing a list of memories within a space

ListMemoryPageImagesResponse

Page of memory page-image metadata

MemoryPageImage

Metadata for one memory page-image rendition

RetrieveMemoryRequest

Request body for semantic memory retrieval with optional embedder weight overrides.

ContextItem

Context item with either text or binary content.

SpaceKey

Space configuration for retrieval operations with optional embedder weight overrides.

TokenBudget

Soft token budget hint for retrieve request processing.

HnswOptions

Optional request-level overrides for pgvector HNSW search settings. Unset fields inherit server defaults.

PostProcessor

Post-processor configuration for transforming retrieval results. Custom processors are discovered from installed extensions and must be referenced by their fully qualified factory class name. See https://docs.goodmem.ai/docs/reference/post-processors/chat-post-processor/ for the built-in ChatPostProcessor configuration.

LoggingOptions

BinaryContent

Binary content with MIME type for context items.

EmbedderWeight

Per-embedder weight override for retrieval operations.

HnswIterativeScan

Iterative scan modes for HNSW index search.

String enum: "ITERATIVE_SCAN_UNSPECIFIED" · "ITERATIVE_SCAN_OFF" · "ITERATIVE_SCAN_RELAXED_ORDER" · "ITERATIVE_SCAN_STRICT_ORDER"

RetrieveMemoryEvent

Streaming event from memory retrieval operation

ResultSetBoundary

Boundary marker for logical result sets in streaming memory retrieval

AbstractReply

Generated abstractive reply with relevance information

RetrievedItem

A retrieved result that can be either a Memory or MemoryChunk

ChunkReference

Reference to a memory chunk with pointer to its parent memory

MemoryChunkResponse

Memory chunk information