Memory Methods

Gateway builtin tools for interacting with Aleph's memory system.

memory_search

Search the knowledge base for relevant facts.

<builtin_tool>memory_search</builtin_tool>
<parameter name="query">What database did we decide on?</parameter>
<parameter name="limit">5</parameter>

Parameters:

• query (required) — Search query
• limit (optional) — Max results, default 5
• agent_id (optional) — Target agent namespace
• mode (optional) — context | tools | hybrid, default hybrid

Returns: Ranked list of MemoryFact with scores.

memory_reflect

Spec 2. Synthesise a coherent answer from memory instead of returning raw facts.

<builtin_tool>memory_reflect</builtin_tool>
<parameter name="query">Summarise what we know about the user's project requirements</parameter>
<parameter name="depth">comprehensive</parameter>

Parameters:

• query (required) — Question to answer
• depth (optional) — brief | standard | comprehensive, default standard
• agent_id (optional) — Target agent namespace

Returns: Synthesised answer with cited sources.

session_search

Spec B. Search across session transcripts.

<builtin_tool>session_search</builtin_tool>
<parameter name="query">When did we discuss authentication?</parameter>
<parameter name="limit">5</parameter>

Parameters:

• query (required) — Search query
• limit (optional) — Max sessions to return, default 5
• summarise (optional) — true | false, default true

Returns: Matching sessions + AI-generated summary (if summarise=true).

remember

Spec A. Pin a fact to curated hot memory.

<builtin_tool>remember</builtin_tool>
<parameter name="content">User prefers dark mode in all applications</parameter>
<parameter name="priority">8</parameter>

Parameters:

• content (required) — Fact to remember
• priority (optional) — 1-10, higher = more important, default 5
• category (optional) — e.g. preference, fact, warning

Returns: Confirmation with fact ID.

Note: Curated memory is a frozen snapshot. Changes require explicit re-curation.

forget

Remove a fact from memory.

<builtin_tool>forget</builtin_tool>
<parameter name="query">The user's old email address</parameter>

Parameters:

• query (required) — Description of fact to remove
• confirm (optional) — true | false, default false

Returns: List of candidate facts + confirmation prompt (if confirm=false).

memory_status

Check memory system health and statistics.

<builtin_tool>memory_status</builtin_tool>

Returns:

• Total notes count
• Raw memory count (unprocessed)
• Index health (FTS + vector)
• Last dream run timestamp
• Curated memory count

Observability & Governance (memory.* / dreaming.*)

The methods below are RPC methods (not builtin chat tools). They expose read-only observability into the memory pipeline plus dream-daemon control. Writes stay LLM/tool-driven — these surface state, they do not mutate facts.

memory.retrieve_with_trace

Run the real NoteFactRetrieval scoring pipeline and return results plus per-stage telemetry, so you can debug why a fact did or didn't surface.

Parameters:

• query (required) — Search query
• limit (optional) — Max results
• agent_id (optional) — Target agent namespace

Returns: Ranked results plus a trace array of stages, each { stage, count, elapsed_ms, scores }. Stages follow the pipeline order: query → candidate pool → BM25 + vector scores → RRF fusion → cutoff → ranked.

memory.list_corrections

List the correction → distillation lifecycle (read-only). Surfaces how user corrections flow into distilled memory.

Parameters:

• agent_id (optional) — Target agent namespace
• limit (optional) — Max entries

Returns: List of correction records with their distillation state.

dreaming.list_insights

List recent daily synthesis insights produced by the dream daemon, plus dream-run history.

Parameters:

• limit (optional) — Max insights / runs to return

Returns: Recent synthesis notes + dream-run history entries.

dreaming.run_now

Trigger a dream cycle immediately instead of waiting for the scheduled run.

Returns: Confirmation with the triggered dream-run identifier.

These four live in the memory.* and dreaming.* RPC namespaces, alongside the existing memory.search / store / delete / clear / stats / compress methods — distinct from the builtin chat tools documented above.

Method Comparison

Error Handling

All memory methods return structured errors:

See Also

• Memory System — Overview
• Memory Architecture — Implementation
• Memory Evolution — Spec history