Memories

The MemoriesResource provides direct access to memories — listing, filtering, stats, episodes, and consolidation.

Access


user = client.for_user("user-123")
memories = user.memories

Methods

`list(**kwargs)`

List memories with optional filtering.


memories_list = memories.list(limit=50, category="work")
for memory in memories_list:
    print(f"[{memory.type}] {memory.content} (importance: {memory.importance})")

Parameter	Type	Default	Description
`owner_id`	`str \| None`	`None`	Filter by owner
`limit`	`int`	`50`	Number of results
`offset`	`int`	`0`	Pagination offset
`category`	`str \| None`	`None`	Filter by category (e.g. `"personal"`, `"work"`)
`type`	`str \| None`	`None`	Filter by type (e.g. `"fact"`, `"concept"`)

Returns: MemoryList — iterable of Memory objects

`direct(**kwargs)`

List direct memories (high-confidence facts explicitly stated by the user).


direct = memories.direct(category="preferences")
for m in direct:
    print(m.content)

Parameter	Type	Default	Description
`owner_id`	`str \| None`	`None`	Filter by owner
`limit`	`int`	`50`	Maximum number to return
`category`	`str \| None`	`None`	Filter by category

Returns: MemoryList

`derived(**kwargs)`

List derived memories (AI-synthesized insights from combining multiple memories).


derived = memories.derived(limit=10)
for m in derived:
    print(f"{m.content} (derived from: {m.derived_from})")

Parameter	Type	Default	Description
`owner_id`	`str \| None`	`None`	Filter by owner
`limit`	`int`	`50`	Maximum number to return

Returns: MemoryList of DerivedMemory objects (includes derived_from and derivation_reason)

`get(memory_id)`

Get a specific memory by ID.


memory = memories.get("memory-uuid")
print(memory.content)
print(memory.type)        # "fact", "concept", etc.
print(memory.category)    # "personal", "work", etc.
print(memory.importance)  # 0.0 to 1.0
print(memory.source)      # "direct" or "derived"
print(memory.created_at)
print(memory.metadata)

Returns: Memory (or DerivedMemory if derived)

Memory model fields

Field	Type	Description
`id`	`str`	Unique identifier
`content`	`str`	The memory text
`type`	`str`	Memory type (fact, concept, etc.)
`category`	`str \| None`	Category (personal, work, etc.)
`importance`	`float`	Importance score (0.0–1.0)
`source`	`str`	Source: `"direct"` or `"derived"`
`created_at`	`datetime`	When the memory was created
`updated_at`	`datetime`	When the memory was last updated
`metadata`	`dict \| None`	Optional metadata

`delete(memory_id)`

Soft-delete a memory.


memories.delete("memory-uuid")

`stats()`

Get memory statistics.


stats = memories.stats()
print(f"Total: {stats.total_memories}")
print(f"Direct: {stats.direct_memories}")
print(f"Derived: {stats.derived_memories}")
print(f"Relationships: {stats.relationships}")

Returns: MemoryStats

`episodes(**kwargs)`

List temporal episodes (time-windowed memory groups).


episodes = memories.episodes(limit=10)
for ep in episodes:
    print(f"Episode {ep.id}: {ep.entity_count} entities")
    print(f"  {ep.start_time} — {ep.end_time}")
    if ep.summary:
        print(f"  Summary: {ep.summary}")

Parameter	Type	Default	Description
`owner_id`	`str \| None`	`None`	Filter by owner
`limit`	`int`	`20`	Maximum number to return
`start_time`	`datetime \| None`	`None`	Filter by start time
`end_time`	`datetime \| None`	`None`	Filter by end time

Returns: EpisodeList of Episode objects

`create_episode(entity_ids)`

Create a new episode from a list of entity IDs.


result = memories.create_episode(["entity-1", "entity-2", "entity-3"])

Returns: EpisodeList with created episodes

`consolidate(dry_run, threshold_percentile)`

Run adaptive forgetting on memories.


# Preview changes
report = memories.consolidate(dry_run=True)
print(f"Would soft-delete: {report.entities_soft_deleted}")
 
# Run for real
report = memories.consolidate(dry_run=False, threshold_percentile=25.0)
print(f"Status: {report.status}")
print(f"Memory reduction: {report.memory_reduction_pct}%")

Parameter	Type	Default	Description
`dry_run`	`bool`	`True`	Preview changes without making them
`threshold_percentile`	`float`	`30.0`	Percentile below which to soft-delete

Returns: ConsolidationReport with fields status, dry_run, entities_evaluated, entities_soft_deleted, entities_hard_deleted, memory_reduction_pct