io.github.praveen-ilangovan/pensieve

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.

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).

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 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).

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).

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).

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.

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?").

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`).

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`).

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).

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.

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

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.

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).

Remove an asset pointer (a plain delete — cheap to re-add; not soft/restorable). Args: asset: Asset id to remove (asset-N).

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`).

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").

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 entity — re-links it to its notes and restores its thread. Args: entity: Id of the entity to restore.

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").

Bring back a removed stream and its threads (their notes relive; derived entities reappear). Args: stream: Id of the stream 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).

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).

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.

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`).