Console Memories

client.memories exposes read-only access to the memories stored in your org. Use it to audit extraction quality, debug unexpected search results, or build admin dashboards.

from memsy import MemsyClient

client = MemsyClient(base_url="...", api_key="msy_...")

import { MemsyClient } from '@memsy-io/memsy';

const client = new MemsyClient({ baseUrl: '...', apiKey: 'msy_...' });

List memories

result = client.memories.list(
    actor_id="user_42",     # optional: filter to a single actor's memories
    kind="semantic",        # optional: "semantic" | "episodic" | ...
    type="preference",      # optional: "preference" | "fact" | "event" | ...
    status="active",        # optional: "active" | "archived" | "decayed"
    sort="observed_at_desc",# "observed_at_desc" | "strength_desc" | "confidence_desc"
    search="dark mode",     # optional: full-text search over memory text
    limit=50,
    offset=0,
)

print(f"{result.total} total memories")
for m in result.items:
    print(m.memory_id, m.text, m.confidence)

const result = await client.memories.list({
  actorId: 'user_42',         // optional: filter to a single actor's memories
  kind: 'semantic',
  type: 'preference',
  status: 'active',
  sort: 'observed_at_desc',
  search: 'dark mode',
  limit: 50,
  offset: 0,
});

console.log(`${result.total} total memories`);
for (const m of result.items) {
  console.log(m.memoryId, m.text, m.confidence);
}

Pagination is stable across pages — the server always sorts by your chosen sort key with memory_id as a secondary tiebreaker, so iterating offset won't return duplicates or skip records even when many memories share the primary sort value (e.g. identical observed_at).

page_size = 50
offset = 0

while True:
    page = client.memories.list(limit=page_size, offset=offset)
    for m in page.items:
        process(m)
    offset += page_size
    if offset >= page.total:
        break

const pageSize = 50;
let offset = 0;

while (true) {
  const page = await client.memories.list({ limit: pageSize, offset });
  for (const m of page.items) await process(m);
  offset += pageSize;
  if (offset >= page.total) break;
}

Get a single memory

memory = client.memories.get("mem_01abc...")
print(memory.text, memory.strength, memory.tags)
print(memory.scope.level, memory.scope.actor_id)

const memory = await client.memories.get('mem_01abc...');
console.log(memory.text, memory.strength, memory.tags);
console.log(memory.scope.level, memory.scope.actorId);

Stats

Aggregate statistics for all memories in the org:

stats = client.memories.stats()
print(f"Total: {stats.total_memories}, Active: {stats.active_memories}")
print(f"Avg confidence: {stats.avg_confidence:.2f}")
print("By type:", stats.by_type)
print("By kind:", stats.by_kind)
print("Top entities:", stats.top_entities[:5])

const stats = await client.memories.stats();
console.log(`Total: ${stats.totalMemories}, Active: ${stats.activeMemories}`);
console.log(`Avg confidence: ${stats.avgConfidence.toFixed(2)}`);
console.log('By type:', stats.byType);
console.log('By kind:', stats.byKind);
console.log('Top entities:', stats.topEntities.slice(0, 5));

`MemoryItemResource` fields

Field	Type	Description
`memory_id`	`str`	Unique memory ID.
`org_id`	`str`	Owning org.
`scope`	`MemoryScopeInfo`	Scope (level + actor/team/role IDs).
`type`	`str`	Memory type (e.g. `"preference"`, `"fact"`).
`kind`	`str`	Memory kind (e.g. `"semantic"`, `"episodic"`).
`memory_kind`	`str`	Low-level memory kind classification.
`status`	`str`	`"active"`, `"archived"`, or `"decayed"`.
`text`	`str`	The extracted memory text.
`confidence`	`float`	Extraction confidence (0–1).
`strength`	`float`	Reinforcement strength (0–5.0, default 1.0). Not a probability.
`recall_count`	`int`	Number of times this memory was recalled in search.
`decay_half_life_days`	`float`	Days until strength halves.
`pinned`	`bool`	Pinned memories never decay.
`tags`	`list[str]`	Tags from extraction.
`entity_refs`	`list[dict]`	Named entity references.
`source_event_ids`	`list[str]`	IDs of contributing events.
`source_urls`	`list[str]`	Source URLs if applicable.
`summary`	`str \| None`	Short auto-generated summary.
`payload`	`dict \| None`	Raw extraction payload from the LLM, if retained.
`last_recalled_at`	`str \| None`	ISO-8601 timestamp of last search recall.
`observed_at`	`str \| None`	ISO-8601 timestamp of first observation.
`effective_from`	`str \| None`	Start of validity window.
`effective_to`	`str \| None`	End of validity window (`None` = indefinite).
`created_at`	`str \| None`	Record creation timestamp.
`updated_at`	`str \| None`	Last update timestamp.

`MemoryScopeInfo`

@dataclass
class MemoryScopeInfo:
    level: str               # "org" | "role" | "team" | "actor"
    actor_id: str | None = None
    team_id: str | None = None
    role_id: str | None = None

Async usage

from memsy import AsyncMemsyClient

async with AsyncMemsyClient(base_url="...", api_key="msy_...") as client:
    stats = await client.memories.stats()
    result = await client.memories.list(kind="semantic", limit=20)
    memory = await client.memories.get("mem_01abc...")