Module: Pikuri::Memory

Defined in:
lib/pikuri-memory.rb,
lib/pikuri/memory/recall.rb,
lib/pikuri/memory/record.rb,
lib/pikuri/memory/recorder.rb,
lib/pikuri/memory/extension.rb,
lib/pikuri/memory/mem0_client.rb,
lib/pikuri/memory/mem0_server.rb

Overview

Namespace for the durable cross-conversation memory feature. Houses:

  • Extension — the Agent::Extension that wires the recall tool, the automatic per-turn prefetch, and the asynchronous capture queue onto an agent. Pass an instance to c.add_extension inside the Agent.new block.

  • Mem0Client — a thin Faraday HTTP client against a mem0 server (+POST /memories+, POST /search, GET/DELETE /memories, POST /reset). The append-only add / read-time search surface; mem0 owns extraction, embedding, and resolution.

  • Recorder — an off-the-interaction-path extraction queue: a background worker drains enqueued user turns into Mem0Client#add, so a turn never blocks on the ~3s extraction call. Flushed (bounded) on agent close.

  • Record — the value type a Mem0Client row deserializes to (id / text / score / created_at / metadata / event).

  • Recall — the recall Tool subclass for explicit, topic-driven deepening beyond the automatic prefetch slice.

Three retrieval tiers (the layered shape)

  1. **Resident persona** — a small always-in-prompt summary of high-frequency facts, appended once via Configurator#append_system_prompt at construction.

  2. **Automatic prefetch** — Extension#on_user_message embeds the latest user message, searches mem0, and injects a small high-precision slice as a :system <memory-context> block.

  3. **Explicit deepening** — the recall tool, called by the model when the prefetch slice hints there is more.

The same resident-vs-triggered split as pikuri-vectordb‘s vectordb_search / vectordb_read — one mental model across memory and RAG. See DESIGN.md §“The three retrieval tiers”.

Safety posture (v1)

Automatic capture + automatic recall are safe only on an agent with no untrusted ingest and no egress (the @private configuration in ideas/assistant.md): a poisoned memory + an egress leg is the lethal trifecta. Capture feeds *user-role content only*, and recall lands as :system context (never a user turn), so the recall→re-extraction feedback loop cannot form. Porting this onto an egress-capable agent re-opens recall-poisoning and must not be done blindly.

Defined Under Namespace

Classes: Extension, Mem0Client, Mem0Server, Recall, Record, Recorder

Constant Summary collapse

LOADER = 
Zeitwerk::Loader.new