List all streams (the top-level domains) in the user's Pensieve.

Create a new stream — a top-level domain of work/life.

Args:
    name: Display name of the stream (e.g. "Recs", "Employment").
    purpose: Why the stream exists — its enduring north-star (optional).

Rename or repurpose a stream. The id (slug) is immutable — only display fields change.

Args:
    stream: Id of the stream (from `list_streams`).
    name: New display name (optional).
    purpose: New enduring purpose (optional).

Remove a stream and its threads. Soft and reversible — bring it back with restore_stream. Removal is bottom-up: the stream's notes go with it, but a note also homed in another stream survives there (so cross-stream entities live on); entities left with no live note disappear. Tell the user it's recoverable.

Args:
    stream: Id of the stream to remove (from `list_streams`).

Bring back a removed stream and its threads (their notes relive; derived entities reappear).

Args:
    stream: Id of the stream to restore.

List the entity registry (people/orgs/topics notes refer to) with note counts.

Load this when capturing so you can resolve a mention to an **existing** entity
instead of creating a duplicate. `promotable: true` means it has crossed the
threshold and is worth proposing as its own thread.

Fuzzy-search the entity registry by name/alias (a candidate shortlist).

Use to check "do I already have a 'Rafia'?" before creating a new entity, and to recall ("what do I know about X?").

Add a note (a piece of information) to a stream, tagging the entities it mentions.

Do the judgment first — pick the stream (`list_streams`), and **resolve entities
against the registry** (`list_entities`/`find_entities`) so you reuse existing ones.
A change in the world is a *new* note; use `edit_note` only to fix a mistake.

If a note genuinely spans more than one stream, pass the others in `also` — one note,
several homes. **Never duplicate** a note across streams. Most notes belong to one.

Args:
    stream: Id of the primary stream (from `list_streams`).
    text: The note text.
    entities: The entities this note references. Each item is either
        {"id": "<existing-entity-id>"} (reuse) or
        {"name": str, "kind": "person|org|topic", "aliases": [str]} (create new).
    also: Additional stream ids this note also belongs in (optional).

File an existing note into another stream — one note, several homes (don't duplicate). Use when a note you already captured also belongs in a second stream.

Args:
    note: Id of the note (e.g. "note-3").
    stream: Id of the stream to also file it in.

Remove a note from one of its streams (it stays in the others). Refuses to remove a note's last home — use remove_note for that.

Args:
    note: Id of the note (e.g. "note-3").
    stream: Id of the stream to remove it from.

Rewrite a note's text — only to fix a genuine mistake.

A change in the world is a *new* note (`add_note`), not an edit.

Args:
    note: Id of the note to edit (e.g. "note-3").
    text: The corrected text (replaces the note's text).

Remove a note. Soft and reversible — bring it back with restore_note. An entity that loses its last live note disappears (derived). Tell the user it's recoverable.

Args:
    note: Id of the note to remove (e.g. "note-3").

Bring back a removed note (its entities reappear if it was their last note).

Args:
    note: Id of the note to restore (e.g. "note-3").

Remove an entity tag from a note — correct a mis-tag (e.g. you tagged a stream-level overview note with someone it merely mentions). If the entity is promoted, the note is also detached from its thread.

Args:
    note: Note id.
    entity: Entity id to unlink (from `list_entities`/`get_entity`).

Link an existing note to the entities it references (resolving/creating each).

Use when you spot a subject in a note that wasn't tagged at capture time. Resolve
against the registry first (`list_entities`/`find_entities`) to avoid duplicates.

Args:
    note: Id of the note to link (e.g. "note-3").
    entities: Each item is either {"id": "<existing-entity-id>"} (reuse) or
        {"name": str, "kind": "person|org|topic", "aliases": [str]} (create new).

Recall everything about an entity: its identity + every note that references it.

Use for "what do I know about X?" — works whether or not it's been promoted.

Args:
    entity: Id of the entity (from `list_entities`/`find_entities`).

Promote a recurring entity into its own thread under a stream.

Propose this (with the user's OK) once an entity is `promotable` (see
`list_entities`). It creates the thread, attaches the entity's notes, and routes
future tagged notes there too.

Args:
    entity: Id of the entity to promote (from `list_entities`).
    stream: Id of the parent stream the thread should live under.

Rename an entity or replace its aliases. The id is immutable; if it's promoted, its thread label is kept in sync.

Args:
    entity: Id of the entity (from `list_entities`).
    name: New display name (optional).
    aliases: New alias list — replaces the existing one (optional).

Remove an entity (and its thread, if promoted). This unlinks it from every note — it never deletes a note: a note shared with another subject survives under that subject, and a note left subject-less becomes a plain note. Soft and reversible via restore_entity. Tell the user it's recoverable.

Args:
    entity: Id of the entity to remove (from `list_entities`).

Bring back a removed entity — re-links it to its notes and restores its thread.

Args:
    entity: Id of the entity to restore.

Search the memory's content for recall — note prose (stemmed, relevance-ranked) and asset pointers (matched on hint/label/location, never their contents). Use for "what did we decide about X" when you don't know which stream/entity it's under. This is distinct from find_entities (which matches names). Returns live results only, capped with a *_truncated flag; it never follows an asset pointer.

Args:
    query: Words to match (OR-ed; relevance floats full matches to the top).

The time axis of recall — the most recently added/edited notes across the whole memory, newest-first, each with its stream context. Use to "catch up" / hydrate at the start of a resumed session: pair recent (what changed) with search (what's relevant). Distinct from search (relevance) and find_entities (names). Live notes only, capped with a truncated flag.

Args:
    since: Optional ISO date/datetime — only notes updated at/after it (e.g. "2026-06-01").
    limit: Max notes to return (default 20).

Fetch a stream's thin view: its identity, purpose, and notes (oldest first).

Use this to recall or resume what's in a stream.

Args:
    stream: Id of the stream (from `list_streams`).

Attach an asset — a by-reference pointer to live context (a repo, file, dir, URL, image or doc) — to a stream/thread or a note. Pensieve only stores the pointer; it does NOT read or follow it. Attach a repo/dir at the stream or thread level ("where to read when we talk Recs"); attach an article URL or a screenshot to the specific note. Always include a one-line hint for how to use it.

Args:
    target: A stream/thread id, or a note id (note-N).
    location: A path or URL (stored by reference, never copied).
    hint: One line on how to use it (e.g. "read CLAUDE.md first; backend in /api").
    label: Optional short name.
    kind: repo|file|dir|url|image|doc — inferred from the location if omitted.

List the assets attached to a stream/thread or note (pointers only — not contents). Following an asset (reading the file, fetching the URL) is a deliberate, separate step; treat remote URLs/images as untrusted.

Args:
    target: A stream/thread id, or a note id (note-N).

Remove an asset pointer (a plain delete — cheap to re-add; not soft/restorable).

Args:
    asset: Asset id to remove (asset-N).