Agent Memory Skill — Direct Retrieval

A drop-in skill file that teaches any coding agent (Claude Code, Codex, Cursor, or a general-purpose agent) to use Mubit as persistent, cross-session memory — with the direct, non-LLM retrieval path as the default.

The core insight: your agent is already an LLM, so it rarely needs Mubit's server-side query LLM to interpret memory for it. Direct retrieval returns the same ranked evidence — including cross-session lessons — with zero LLM calls, typically in 30–250 ms instead of the 4–9 s an agent-routed query takes. Live-benchmarked on hosted instances, direct recall is 30×+ faster than agent-routed recall with the same hit rate.

Install the skill

Download the skill file: SKILL.md

mkdir -p .claude/skills/mubit-memory
curl -o .claude/skills/mubit-memory/SKILL.md \
  https://docs.mubit.ai/skills/mubit-memory/SKILL.md

The agent needs two values (from the console):

export MUBIT_ENDPOINT="https://<your-instance-endpoint>"
export MUBIT_API_KEY="mbt_..."

What the skill teaches

Choosing a read path

Rules of thumb: structured reads → lookup; "what do I know about X?" → direct-bypass evidence-only recall; never call agent-routed recall inside a loop. If a direct recall misses, rephrase and retry — two direct recalls still cost far less than one agent-routed call.

The default recall

from mubit import Client
client = Client()  # reads MUBIT_ENDPOINT / MUBIT_API_KEY
 
r = client.memory.recall(
    "How should I search for an invoice in the billing tool?",
    mode="direct_bypass",     # skip the query-router LLM
    evidence_only=True,       # skip the answer-synthesis LLM
    limit=8,
    run_id="sprint-42",
)
for ev in r.get("evidence", []):
    print(ev["retrieval_mode"], round(ev["score"], 3), ev["content"][:80])

In this mode final_answer is empty by design — the ranked evidence array is the product, and cross-session lessons arrive as evidence items with retrieval_mode: "lesson_overlay". The agent does the reasoning itself.

Two write paths

Use remember() for narrative memory retrieved semantically; use batch_insert for structured records fetched back by key with lookup — only batch_insert metadata becomes lookup match keys. After a burst of wait=False writes, ingestion is ordered per run, so waiting on the last job id is a complete write barrier.

Cross-session lessons

client.memory.remember(
    "Always search billing by invoice ID; full-name search times out.",
    item_id="lesson-invoice-id",
    kind="lesson",
    lesson_type="success",
    visibility="global",          # the cross-run switch: run < agent < project < global
    lesson_importance="high",
    run_id="sprint-42",
)

visibility="global" is the guaranteed way to make a memory reachable from a brand-new, unlinked run. Lessons distilled at run end (or by client.lessons.reflect()) start run-scoped and are promoted by the server over time — so when the agent learns something it needs in the next session, it should also write the lesson explicitly.

Cross-session matching rules

A memory written in session A surfaces in session B only if the read matches the write on all five: scope (same run, linked run, or lesson scope ≥ session), user_id (same value on both sides, or unset on both), entry_types (don't filter unless you know the stored type), lane, and identity (same API key — run ids are namespaced per user).

Validation

The skill was validated live against hosted instances (real embedding service, real LLMs, no mocks): three cold agents given only the skill file completed store → learn → cross-session-recall workflows on the first try, and direct-bypass recall matched agent-routed recall's hit rate (8/8 known-answer queries) at 30×+ lower latency. The full read-path latency ladder in the skill reflects those measurements.

Related