Types

Every method returns a frozen dataclass rather than a protobuf message, so the generated code stays an implementation detail and values arrive in their natural Python form.

Immutable result types returned by the Memco SDK.

Every method returns one of these frozen dataclasses rather than a protobuf message. That keeps the generated code an implementation detail, and lets the SDK present values in their natural Python form: dates as datetime.date, enumerations as enum.Enum, repeated fields as tuples, and genuinely absent strings as None.

Values are immutable, so a result can be cached or shared between threads without defensive copying.

class AsyncMemory(idx, kind, times_served, intents, insights, reference, _operations=None, _session_id='')[source]

Bases: object

One memory, with the insights sampled from it, on an asyncio client.

Mirrors Memory; see it for what each attribute means, including the live reference this carries and why that keeps it from being deep-copied, pickled, or passed through dataclasses.asdict().

Variables:

  • idx (str) – Handle addressing this memory.

  • kind (str) – The memory’s kind, as reported by the service.

  • times_served (int) – How often this memory has been delivered, this delivery included.

  • intents (tuple[str, ...]) – The questions this memory has been retrieved by, oldest first.

  • insights (tuple[Insight, ...]) – The insights sampled from this memory. Empty when reference is set.

  • reference (str | None) – The handle an earlier search in the same session returned this memory under.

Parameters:
idx: str
kind: str
times_served: int
intents: tuple[str, ...]
insights: tuple[Insight, ...]
reference: str | None
async feedback(*, relevant, correct, comment=None)[source]

Rate this memory: whether it was relevant, and whether it was correct.

A shortcut for calling share_feedback() with a single FeedbackRating built from this memory’s own idx.

Parameters:

  • relevant (bool) – Whether the result was a good match for the query.

  • correct (bool) – Whether its content was accurate.

  • comment (str | None) – An optional note about this result.

Returns:

The rating that was recorded.

Raises:
Return type:

FeedbackEntry

Example

>>> entry = await memory.feedback(relevant=True, correct=True)
class DataSource(value)[source]

Bases: Enum

Who produced the content of a write.

Variables:

  • UNSPECIFIED – Not stated. The service reads this as AGENT.

  • USER – The content came from a human.

  • AGENT – The content came from an agent. This is the usual value and the SDK’s default.

UNSPECIFIED = 0
USER = 1
AGENT = 2
classmethod from_wire(value)[source]

Convert a wire value, tolerating one this SDK does not know.

Parameters:

value (int) – The enum value as it arrived on the wire.

Returns:

The matching member, or UNSPECIFIED if the service sent a value added after this SDK was released.

Return type:

DataSource

class DomainEntry(slug, title, summary, when_to_search, when_to_save, what_not_to_save, tags_description, filter_tag_types, version_tag_types, max_tags_per_query)[source]

Bases: object

One memory domain: what it holds and the tag vocabulary it uses.

Variables:

  • slug (str) – The value to pass as the domain argument elsewhere.

  • title (str) – Human-readable name.

  • summary (str) – What the domain holds.

  • when_to_search (str) – When to draw on it.

  • when_to_save (str) – What is worth writing to it.

  • what_not_to_save (str) – What must never be written to it.

  • tags_description (str) – Rendered description of the tag vocabulary.

  • filter_tag_types (tuple[str, ...]) – Tag types that narrow results rather than boost them. This is the distinction that decides whether a wrong tag returns nothing at all.

  • version_tag_types (tuple[str, ...]) – Tag types that carry a version. A version on any other type is dropped.

  • max_tags_per_query (int) – Bounds the tags on a call naming this domain. Trimmed rather than refused, and per-domain rather than global. Zero means this domain sets no cap.

Parameters:

  • slug (str)

  • title (str)

  • summary (str)

  • when_to_search (str)

  • when_to_save (str)

  • what_not_to_save (str)

  • tags_description (str)

  • filter_tag_types (tuple[str, ...])

  • version_tag_types (tuple[str, ...])

  • max_tags_per_query (int)

slug: str
title: str
summary: str
when_to_save: str
what_not_to_save: str
tags_description: str
filter_tag_types: tuple[str, ...]
version_tag_types: tuple[str, ...]
max_tags_per_query: int
class DomainList(domains, instructions, limits, deprecated, deprecation_message, sunset_date, server_commit)[source]

Bases: object

The domains the caller may name.

Variables:

  • domains (tuple[memcoai.types.DomainEntry, ...]) – The available domains.

  • instructions (memcoai.types.Instructions) – Guidance accompanying the result.

  • limits (memcoai.types.Limits | None) – The caps the service enforces on request fields, or None against a service that does not report them. None means do not validate, never zero.

  • deprecated (bool) – Whether what this caller is using has been superseded — either the API version or this SDK build. Which of the two is deliberately not distinguished here; deprecation_message says.

  • deprecation_message (str) – The service-authored remedy, empty when nothing is deprecated. It is the whole of what a caller should be shown.

  • sunset_date (datetime.date | None) – When what the caller uses stops working, or None when no date is set — which is not a promise that none will be.

  • server_commit (str) – The build that answered this call, for quoting in a bug report. Empty against a service that does not report one. This is not provenance()’s server_commit, which is the commit the installed package was generated from.

Parameters:
domains: tuple[DomainEntry, ...]
instructions: Instructions
limits: Limits | None
deprecated: bool
deprecation_message: str
sunset_date: date | None
server_commit: str
class FeedbackEntry(idx, relevant, correct, advice)[source]

Bases: object

One rating that was recorded.

Variables:

  • idx (str) – The handle that was rated.

  • relevant (bool) – The relevance verdict that was recorded.

  • correct (bool) – The correctness verdict that was recorded.

  • advice (str | None) – The suggestion this particular verdict earned, or None when the verdict suggests nothing. It addresses one result, so it belongs to the entry rather than to the batch.

Parameters:
idx: str
relevant: bool
correct: bool
advice: str | None
class FeedbackRating(idx, relevant, correct, comment=None)[source]

Bases: object

One rating to give a search result.

Variables:

  • idx (str) – Handle copied exactly from a search result. An insight’s handle rates that insight; a memory’s own handle rates every insight under it. It cannot be constructed by hand.

  • relevant (bool) – Whether the result was a good match for the query.

  • correct (bool) – Whether its content was accurate.

  • comment (str | None) – An optional note about this result.

Parameters:

Example

>>> from memcoai.types import FeedbackRating
>>> FeedbackRating(idx="memory-a-1-insight-1", relevant=True, correct=True)
FeedbackRating(idx='memory-a-1-insight-1', relevant=True, correct=True, comment=None)
idx: str
relevant: bool
correct: bool
comment: str | None
to_proto()[source]

Convert to the wire message.

Returns:

The protobuf FeedbackRating, with comment left unset when it is None.

Return type:

FeedbackRating

class FeedbackResult(session_id, entries, instructions)[source]

Bases: object

The ratings that were recorded for one search.

Variables:
Parameters:
session_id: str
entries: tuple[FeedbackEntry, ...]
instructions: Instructions
class ImportOutcome(index, status, errors)[source]

Bases: object

What happened to one memory of an imported batch.

An import mints no handle a caller could name a memory by, so an outcome is addressed by the position its memory held in the request.

Variables:

  • index (int) – The position of this memory in the submitted batch.

  • status (memcoai.types.ImportStatus) – What became of it.

  • errors (tuple[str, ...]) – What was wrong with an entry that was not queued. Empty for one that was.

Parameters:
index: int
status: ImportStatus
errors: tuple[str, ...]
class ImportResult(results, instructions)[source]

Bases: object

What an import accepted.

Each memory is written asynchronously, so this reports what was accepted rather than what now exists. There is no operation id: a batch mints none, and nothing undoes an import.

Variables:
Parameters:

Example

>>> result = client.memory.import_memories(batch, domain="coding")
>>> [(o.index, o.status.name) for o in result.results]
[(0, 'QUEUED'), (1, 'DUPLICATE')]
results: tuple[ImportOutcome, ...]
instructions: Instructions
class ImportStatus(value)[source]

Bases: Enum

What became of one memory of an imported batch.

Every memory is judged on its own, so a refused entry does not stop the others. None of these is an error: each reports what happened to one entry of a call that succeeded.

Variables:

  • UNSPECIFIED – No status was reported.

  • QUEUED – Accepted and queued for writing.

  • REJECTED – The entry itself was not usable; its errors say what about it.

  • ERROR – The entry was usable but could not be queued. Resubmitting it is the remedy: an import is written under an identity derived from its own content, so a memory that did land is not duplicated by sending it again.

  • DUPLICATE – The content is already in memory, so nothing was written and nothing was charged. Sending the same batch again is safe and free.

UNSPECIFIED = 0
QUEUED = 1
REJECTED = 2
ERROR = 3
DUPLICATE = 4
classmethod from_wire(value)[source]

Convert a wire value, tolerating one this SDK does not know.

Parameters:

value (int) – The enum value as it arrived on the wire.

Returns:

The matching member, or UNSPECIFIED if the service sent a value added after this SDK was released.

Return type:

ImportStatus

class ImportedInsight(title, content)[source]

Bases: object

One insight to contribute as part of an imported memory.

Variables:

  • title (str) – (Required) A short title describing what this insight is about. Title and content together must be at most 5000 characters.

  • content (str) – (Required) The knowledge to save. Should be a concise, non-trivial finding that others can learn from. Supports markdown formatting.

Parameters:

Example

>>> from memcoai.types import ImportedInsight
>>> ImportedInsight(title="Bearer is case-sensitive",
...                 content="Lowercase 'bearer' is rejected.")
ImportedInsight(title='Bearer is case-sensitive', content="Lowercase 'bearer' is rejected.")
title: str
content: str
to_proto()[source]

Convert to the wire message.

Returns:

The protobuf ImportedInsight.

Return type:

ImportedInsight

class ImportedMemory(queries, insights, tags=None)[source]

Bases: object

One memory to contribute: what it should be found by, and what it holds.

Variables:
Parameters:

Example

>>> from memcoai.types import ImportedInsight, ImportedMemory, Tag
>>> memory = ImportedMemory(
...     queries=["how do I authenticate against the memory API"],
...     insights=[ImportedInsight(title="Bearer is case-sensitive",
...                               content="Lowercase 'bearer' is rejected.")],
...     tags=[Tag(type="language", value="python")],
... )
queries: Iterable[str]
insights: Iterable[ImportedInsight]
tags: Iterable[Tag] | None
class Insight(idx, title, content, updated, times_served, endorsed, disputed)[source]

Bases: object

One insight held under a memory.

Variables:

  • idx (str) – Handle addressing this insight. Copy it exactly; it cannot be constructed by hand.

  • title (str) – Short title.

  • content (str) – The insight itself.

  • updated (datetime.date | None) – The day the insight was last written. Enrichment edits an insight in place, so this is the age of the knowledge rather than of the record. None if the service sent no parseable date.

  • times_served (int) – How often this insight has been delivered to anyone. It records deliveries and nothing else: a frequently served insight is not thereby a correct one, which is what endorsed and disputed answer.

  • endorsed (int) – How many callers rated this insight correct.

  • disputed (int) – How many callers rated it incorrect.

Parameters:
idx: str
title: str
content: str
updated: date | None
times_served: int
endorsed: int
disputed: int
class Instructions(content, policy, adding, rating, next)[source]

Bases: object

Model-facing guidance accompanying a result.

Held apart from the data so a caller can render its own document or use this one. Each part arrives already rendered for its domain, and a part with nothing to say is an empty string rather than None.

Variables:

  • content (str) – What the result is, or what happened.

  • policy (str) – How a policy result outranks the rest. Non-empty only when one was returned.

  • adding (str) – How to contribute back to what came back.

  • rating (str) – How to rate what came back.

  • next (str) – The follow-up call this result enables, such as the handle that undoes a write.

Parameters:
content: str
policy: str
adding: str
rating: str
next: str
class Limits(max_query_characters, max_text_characters, max_idx_characters, max_sources, max_feedback_entries, max_import_memories, max_import_queries_per_memory, max_import_insights_per_memory, max_import_tags_per_memory)[source]

Bases: object

The caps the service enforces on request fields.

Delivered by list_domains() so the service owns them: an SDK carrying its own numbers would keep rejecting requests the service had started accepting. A client that has not asked for them validates nothing and lets the service rule.

Variables:

  • max_query_characters (int) – Bounds query on search and on a create. Exceeding it is refused.

  • max_text_characters (int) – Bounds title and content together, not each. Exceeding it is refused.

  • max_idx_characters (int) – Bounds every handle-shaped value — idx, memory_idx, and each entry of sources. Exceeding it is refused.

  • max_sources (int) – Bounds sources on an enrichment. Trimmed rather than refused: the service keeps the first this many, so a client trims to match instead of rejecting a call the service would accept.

  • max_feedback_entries (int) – Bounds the ratings in one feedback call. Exceeding it is refused.

  • max_import_memories (int) – Bounds the memories in one import call — one call, not one batch. Exceeding it is refused, so the SDK divides a longer batch into groups of this size and makes several calls; a caller does not have to chunk against it.

  • max_import_queries_per_memory (int) – Bounds the queries on one imported memory. Exceeding it is refused.

  • max_import_insights_per_memory (int) – Bounds the insights on one imported memory. Exceeding it is refused.

  • max_import_tags_per_memory (int) – Bounds the tags on one imported memory. Exceeding it is refused — unlike the per-domain cap reported by DomainEntry.max_tags_per_query, which trims.

Parameters:

  • max_query_characters (int)

  • max_text_characters (int)

  • max_idx_characters (int)

  • max_sources (int)

  • max_feedback_entries (int)

  • max_import_memories (int)

  • max_import_queries_per_memory (int)

  • max_import_insights_per_memory (int)

  • max_import_tags_per_memory (int)

max_query_characters: int
max_text_characters: int
max_idx_characters: int
max_sources: int
max_feedback_entries: int
max_import_memories: int
max_import_queries_per_memory: int
max_import_insights_per_memory: int
max_import_tags_per_memory: int
class Memory(idx, kind, times_served, intents, insights, reference, _operations=None, _session_id='')[source]

Bases: object

One memory, with the insights sampled from it.

A memory returned by the SDK – by a search, or by get_memory() – keeps a reference to the namespace that produced it, which is what lets feedback() rate it without the caller naming a session again, and keeps the client that produced it alive for as long as this memory is referenced. That live reference also means such a memory cannot be deep-copied, pickled, or passed through dataclasses.asdict(): all three raise, since there is a live gRPC channel underneath. Only a Memory built by hand, naming no operations at all, carries none of these restrictions.

Variables:

  • idx (str) – Handle addressing this memory.

  • kind (str) – The memory’s kind, as reported by the service.

  • times_served (int) – How often this memory has been delivered, this delivery included.

  • intents (tuple[str, ...]) – The questions this memory has been retrieved by, oldest first. They describe what it answers; none of them is “the one that matched”, since a memory is retrieved whole.

  • insights (tuple[Insight, ...]) – The insights sampled from this memory. Empty when reference is set.

  • reference (str | None) – The handle an earlier search in the same session returned this memory under. When set, the memory is already in the caller’s context under that handle and no insights are repeated here; pass this result’s own idx to get_memory() to read it again.

Parameters:
idx: str
kind: str
times_served: int
intents: tuple[str, ...]
insights: tuple[Insight, ...]
reference: str | None
feedback(*, relevant, correct, comment=None)[source]

Rate this memory: whether it was relevant, and whether it was correct.

A shortcut for calling share_feedback() with a single FeedbackRating built from this memory’s own idx.

Parameters:

  • relevant (bool) – Whether the result was a good match for the query.

  • correct (bool) – Whether its content was accurate.

  • comment (str | None) – An optional note about this result.

Returns:

The rating that was recorded.

Raises:
Return type:

FeedbackEntry

Example

>>> entry = result.memories[0].feedback(relevant=True, correct=True)
class MemoryT

Which memory type a SearchResult holds – Memory for the synchronous client, AsyncMemory for the asyncio one. Kept as a constrained type variable rather than a plain union so that a memory’s own feedback() is typed as sync or async, never as both at once.

alias of TypeVar(‘MemoryT’, ~memcoai.types.Memory, ~memcoai.types.AsyncMemory)

class ProtoRecord(path, sha256)[source]

Bases: object

One contract file the generated client was built from.

Variables:

  • path (str) – Path of the .proto within the contract tree.

  • sha256 (str) – Hex-encoded SHA-256 of that file’s contents.

Parameters:
path: str
sha256: str
class Provenance(server_commit, protos)[source]

Bases: object

Which version of the contract this SDK’s generated client came from.

Read from the descriptor the export ships inside the package, so it describes the installed artifact rather than the repository it was built in.

Variables:

  • server_commit (str) – Commit of the server repository that produced the generated client.

  • protos (tuple[memcoai.types.ProtoRecord, ...]) – The contract files it was generated from, with their checksums.

Parameters:

Example

>>> provenance().server_commit  # the commit this wheel was built from
'762721a87ab0...'
server_commit: str
protos: tuple[ProtoRecord, ...]
class RevertOutcome(value)[source]

Bases: Enum

What a revert actually removed.

A revert reports the effect it had rather than the operation that was asked for, so several of these describe a successful call that removed nothing.

Variables:

  • UNSPECIFIED – No outcome was reported.

  • MEMORY_REMOVED – The reverted insight was its memory’s last, so the memory and its orphaned intents went with it.

  • ADDITION_REMOVED – Only the caller’s insight was removed; its memory holds others and stays.

  • ENTRY_REMOVED – The caller’s insight was removed and no memory was involved, which is what happens to a write the validator rejected.

  • MERGED – The write had been folded into an existing insight as an endorsement. The duplicate was removed and the endorsed insight is untouched.

  • NOT_FOUND – No write by this caller carries that operation id, either because it never existed or because its ingestion is still running.

  • EXPIRED – The operation is older than the revert window.

  • REFUSED – The content is under moderation and only a moderator may remove it.

UNSPECIFIED = 0
MEMORY_REMOVED = 1
ADDITION_REMOVED = 2
ENTRY_REMOVED = 3
MERGED = 4
NOT_FOUND = 5
EXPIRED = 6
REFUSED = 7
classmethod from_wire(value)[source]

Convert a wire value, tolerating one this SDK does not know.

Parameters:

value (int) – The enum value as it arrived on the wire.

Returns:

The matching member, or UNSPECIFIED if the service sent a value added after this SDK was released.

Return type:

RevertOutcome

class RevertResult(operation_id, outcome, instructions)[source]

Bases: object

What a revert removed.

Every outcome arrives as a successful call. NOT_FOUND, EXPIRED and REFUSED report caller-visible state rather than a service failure, so they are values here rather than exceptions.

Variables:
Parameters:

Example

>>> result = client.memory.revert_memory("create-abc")
>>> if result.outcome is RevertOutcome.EXPIRED:
...     print("too late to undo that one")
operation_id: str | None
outcome: RevertOutcome
instructions: Instructions
class SearchResult(session_id, memories, notice, instructions)[source]

Bases: Generic[MemoryT]

What a search selected.

Variables:

  • session_id (str) – The session this search was recorded under. Reuse it for follow-up searches and for rating these results.

  • memories (tuple[memcoai.types.MemoryT, ...]) – The memories selected, in rendered order. Empty when the search selected nothing.

  • notice (str | None) – A remark about the query itself rather than about its results, or None when there is nothing to say.

  • instructions (memcoai.types.Instructions) – Guidance accompanying the result.

Parameters:
session_id: str
memories: tuple[MemoryT, ...]
notice: str | None
instructions: Instructions
class Tag(type, value, version=None)[source]

Bases: object

One selector on a search or a write.

The service lowercases each field and folds hyphens to underscores, so "Go" and "go" name the same tag. Which types exist, which of them narrow results rather than boost them, and which carry a version are all per-domain; list_domains() describes them.

Variables:

  • type (str) – The tag’s category, such as "language" or "framework".

  • value (str) – The value within that category, such as "python".

  • version (str | None) – Version of the thing named, where its type carries one. A version on a type that does not carry one is dropped by the service. Most tag types carry no version, so this is usually None.

Parameters:

  • type (str)

  • value (str)

  • version (str | None)

Example

>>> from memcoai.types import Tag
>>> Tag(type="language", value="python", version="3.12")
Tag(type='language', value='python', version='3.12')
type: str
value: str
version: str | None
to_proto()[source]

Convert to the wire message.

Returns:

The protobuf Tag, with version left unset when it is None.

Return type:

Tag

class ToolDescriptor(name, description, available)[source]

Bases: object

One method the contract declares, and whether the caller’s role permits it.

Variables:

  • name (str) – The method’s operation name, such as "search" or "create_memory" — the same canonical snake_case name tools() prefixes with memco_ for a model.

  • description (str) – What the method is for.

  • available (bool) – Whether the caller’s role permits this method. False is a fact about their own account, not about the method: a caller told True may still have a call refused for an unrelated reason, such as a memory domain with no network provisioned for it.

Parameters:
name: str
description: str
available: bool
class WriteResult(operation_id, instructions)[source]

Bases: object

The outcome of a write, which the service accepts asynchronously.

Because the write is still being ingested, the result addresses the operation rather than the memory it will become.

Variables:

  • operation_id (str | None) – Handle addressing the write, for revert_memory(). None when no handle could be minted: the content is worth more than the ability to undo it, so a numbering failure degrades to an un-revertible write rather than a rejected one.

  • instructions (memcoai.types.Instructions) – Guidance accompanying the result.

Parameters:
operation_id: str | None
instructions: Instructions