Agent Integrations¶

Membrick connects to agent clients through lifecycle hooks and a shared file-based memory index. Each adapter preserves the host client protocol while using the same capture, indexing, and retrieval model.

Supported agents¶

All agents share the single project store at .membrick/memory/ — a decision recorded by Claude is visible to Codex, and vice versa. Provider attribution travels on each document (integration, author_agent, {provider}-session:{id} group ids), not in the directory layout.

Upgrading from an older version? Legacy per-provider stores (.membrick/claude-memory/, .membrick/codex-memory/, .membrick/gemini-cli-memory/, .membrick/agy-memory/, .membrick/muse-memory/) are migrated into .membrick/memory/ automatically on first run and removed once their migration succeeds. A failed migration leaves the legacy directory untouched, so no memory is lost.

How an agent uses memory¶

1. A lifecycle hook receives the agent event and transcript context.
2. Retrieval hooks query the existing MemoryService and return relevant context to the agent.
3. Claude Code and Codex capture hooks preserve every parsed transcript observation with its speaker and source order, including structured tool and image blocks serialized from the transcript. Other adapters capture the observations available in their provider payloads.
4. The adapter upserts the document and refreshes the index snapshot.
5. The next prompt can query the newly refreshed snapshot.

See Server and MCP for direct API access.

Memory lifecycle¶

All supported adapters retrieve memory during an active turn and capture new memory at lifecycle boundaries. The exact hook names vary by client, but the contract is the same: query the current snapshot, capture durable context, then refresh the snapshot.

One turn inside a session¶

sequenceDiagram
    participant U as User
    participant A as Agent<br/>(Codex · Claude Code · Gemini CLI · AGY)
    participant H as Lifecycle hook
    participant I as Membrick

    U->>A: Submit prompt
    A->>H: UserPromptSubmit
    H->>I: Query existing memories
    I-->>H: Ranked excerpts
    H-->>A: Inject context in hook response
    A->>H: PreToolUse / PostToolUse (optional)
    H->>I: Query existing memories
    I-->>H: Ranked excerpts
    H-->>A: Inject context for next decision
    A-->>U: Complete response
    A->>H: Stop / AfterAgent
    H->>H: Preserve available session observations
    H->>I: Upsert outcome + refresh snapshot

1. User submits a prompt
2. Retrieval hook queries the existing MemoryService
3. Agent may call tools (pre-tool and post-tool hooks can retrieve context)
4. Agent finishes the turn
5. Stop/AfterAgent captures the turn outcome and refreshes MemoryService
6. The next prompt can retrieve that captured outcome

Stop (or Gemini CLI's AfterAgent) is a per-turn boundary and can occur multiple times in one session. It is different from SessionEnd, which runs when the entire session closes and captures the final session summary:

Turn 1 → Stop       capture outcome
Turn 2 → Stop       capture outcome
Turn 3 → Stop       capture outcome
Session exits → SessionEnd   capture session summary

The current turn is not retroactively re-prompted with its newly captured memory. That memory is injected on a later retrieval event.

Retrieval events¶

Adapters query their provider-specific MemoryService on events such as:

• SessionStart
• UserPromptSubmit
• PreToolUse and PostToolUse
• SubagentStart

Selected records are returned as additional context to the client. Queries are scoped to the active project and provider memory store.

Retrieval and injection path¶

Agent hook receives prompt/tool context
        ↓
Adapter builds a provider-scoped query
        ↓
MemoryService ranks matching records with project/user filters
        ↓
Adapter bounds and formats the selected excerpts
        ↓
Hook response returns the context to the host agent
        ↓
Host agent includes it in the next model/tool decision

The adapter does not rewrite the original user prompt. It uses each client’s hook response protocol:

If the query is empty, the store is absent, or no relevant records survive filtering, the hook returns no injected context and the agent continues normally.

Turning the integration on and off¶

Memory behavior and session recording are independent controls exposed through the provider’s Membrick MCP server:

The controls are project- and provider-scoped. Disabling the integration does not uninstall hooks, delete the index, or delete session archives; it only prevents Membrick from participating in subsequent turns.

Hook events recorded for replay (no index update)¶

When session recording is enabled, the adapters record every supported hook invocation for replay and diagnostics. These records are telemetry; they do not update the searchable MemoryService:

Events that update searchable memory¶

At a capture event, Claude Code and Codex read the complete transcript and preserve every parsed message and structured block in source order, after credential redaction. Their stable session document is upserted on each capture instead of storing another full copy for every turn. Other adapters capture the session data exposed in their hook payloads. Claude and Codex send each capture as one upsert batch. The hook returns once the batch is journaled, and the document becomes searchable on the next background publication. It is not injected back into the conversation that just ended. The document is returned on a later retrieval event, typically the next prompt or next session. If the transcript is missing or has no parsed messages, the event completes without adding a document.

Two kinds of persistence¶

• MemoryService contains searchable memory documents.
• Session recording archives raw provider hook events for replay and debugging.

Recording a hook event does not by itself make a document searchable; it must also pass through the provider's capture and index-refresh path.

The HTTP/MCP API follows the same guarantee: a successful memory_add performs the upsert and refresh before returning, so a subsequent memory_search can query the new memory immediately.

Provider-specific benchmarks¶

The benchmark overview, cross-client integration benchmark, and provider benchmark pages document standalone retrieval, corpus-scale, and integration measurements for these adapters.

Session recording is documented separately in Session recording. It records lifecycle events for replay and inspection and is intentionally independent from searchable memory and context injection.

The provider MCP tools and their request semantics are documented in the MCP interface guide. For onboarding, see the Get started entries for the HTTP server and MCP interface.