memU Agent-Driven Memory System

Events reported by the memu-cli are categorized by their provenance using the context.reported_by field. This field is a fact about how the event was generated and is located in the context object, not in properties.

• code: Events observed and emitted directly by the CLI logic (e.g., an unhandled exception or a successful store call).
• agent: Events reported voluntarily by an AI agent (e.g., an agent deciding a task has failed and calling a report command).

Distinguishing between these allows developers to separate "failures the code observed" from "failures a model reported."

The project uses a unified vocabulary for its memory and skill storage. The core entities are:

• RecallFile: A top-level container (formerly MemoryCategory). It represents a category or a skill. It includes a track column to distinguish between types and a content column (formerly summary) for the body text.
• RecallFileEntry: An item within a RecallFile (formerly CategoryItem).
• RecallEntry: A specific piece of data (formerly MemoryItem). Note that RecallEntry still uses the field name summary for its content, even though RecallFile was renamed to content.

Tracks:

• track="memory": Standard categorized memory.
• track="skill": Synthesized skills generated during the workspace memorization workflow.

Pagination in memU is designed to be identical across both local (in-process) and cloud (HTTP) execution paths.

1. Source of Truth: The pagination logic (page size, ordering, and cursor encoding) lives in the AgenticMixin. This ensures that the cloud client and the memu-service server always see the same data shape.
2. Keyset Resumption: To prevent data drift (skipping or duplicating rows during concurrent writes), memU uses keyset pagination. The cursor is an opaque, base64-encoded token representing the tuple (track, name, id).
3. Efficiency: Instead of slicing a full list in memory, the repository performs a bounded query: WHERE scope AND (track,name,id) > cursor ORDER BY track,name,id LIMIT n+1. This allows the database to seek directly to the next page without scanning the entire table.

memU turns agent history into reusable Markdown skills through a six-step pipeline:

1. Capture new sessions: The host adapter reads session history (messages and tool calls).
2. Prepare self-evolve jobs: prepare slices sessions into self-contained jobs with necessary context.
3. Let the agent decide: The agent reads existing skills and decides whether to do nothing, patch an existing skill, or create a new one.
4. Write readable skill Markdown: Skills are written with a name, description, and reusable workflow (including edge cases and pitfalls).
5. Commit and index: commit submits changes via commit_results; memU embeds the name/description and stores it under the skill track.
6. Retrieve it later: On similar future tasks, memU returns the relevant skill for the agent to use.

For agents that do not have a dedicated memU adapter, you can use the memu-agent binary (from the memu.hosts.generic package). This adapter uses a heuristic approach to integrate with agents by detecting two specific 'seams':

1. Memorization (Record Seam): Works if the agent logs sessions in one of the ~5 supported JSONL dialects (e.g., Codex, OpenClaw, Claude Code, Cursor, or flat OpenAI-client chat rows).
2. Retrieval (Inject Seam): Works if the agent uses recognizable instruction files (e.g., AGENTS.md, CLAUDE.md, or SOUL.md).

Integration can be partial (only memorization or only retrieval) or full (both). The detect command is used to determine which capabilities are available for a specific agent directory.

The memU CLI reports a fixed set of six lifecycle events to the ingest endpoint to assist in diagnosing silent failures or configuration mismatches:

1. install completed: Triggered when the installation process finishes.
2. uninstall: Triggered during uninstallation.
3. bridging (remember) run finished: Triggered when a bridging task completes.
4. retrieval: Triggered during a memory retrieval operation.
5. listing of the store: Triggered when the store contents are listed.
6. fatal error: Triggered when a critical error occurs.

Every memory line follows a three-layer derivation model. Data flows from raw sources to fine-grained searchable items. This hierarchy ensures that while you search at the most granular level, the results are contextually linked to their parent documents.

1. L0 (Resource): The raw source material (e.g., raw chat corpus, raw multimodal data, or raw agent logs).
2. L1 (Document): A coarse document derived from L0 via preprocessing (e.g., a classified memory category, a caption paragraph, or a skill markdown file).
3. L2 (Item): Fine-grained slices or extracts of the L1 document. L2 items are the actual units used for embedding and search.

Retrieval Flow: A query searches across L2 items using hybrid retrieval. When a match is found, the system 'rolls up' the result to its parent L1 document (and its L0 resource) to provide full context to the user or agent.

memU models its core operations—such as memorize, retrieve, and CRUD/patch operations—as named workflow pipelines. Instead of monolithic functions, these operations are composed of ordered WorkflowStep units.

Key components of the pipeline architecture include:

• PipelineManager: Used to register pipelines centrally within the MemoryService.
• WorkflowRunner: The abstraction responsible for executing the pipeline (defaults to a local runner).
• WorkflowStep: The individual units of work that make up a pipeline.
• Interceptors: Support for before, after, and on_error hooks at the step level for instrumentation and control.

This architecture allows for runtime customization through step-level configuration and structural mutations like inserting, replacing, or removing steps.