Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Context engineering

Verbatim vs semantic recall

Semantic memory is paraphrase-prone by design — entries are retrieved by similarity and assembled into context, which is exactly right for insights and preferences and exactly wrong for a config file. This pattern is the discipline of deciding, at write time, whether a future reader needs the exact bytes or the gist — and using archive() for the former. Use it whenever your agent produces artifacts that will be re-executed, quoted, or audited.

How it works

archive(content, artifact_kind, ...) stores the content as an archive_block — immutable, exact, and addressed by the stable reference_id the call returns. dereference(reference_id) fetches it back byte-for-byte, no similarity search involved. Every other entry type is semantic: retrieved by relevance to a query, scored, trimmed, and reworded downstream — reliable for meaning, not for characters.

The two worlds still meet at query time: archived artifacts surface as archive_overlay evidence in normal queries when they're relevant, and as the archive_blocks section in assembled context — see Retrieval lanes. Evidence with referenceable: true carries its reference_id, so anything the overlay surfaces can be re-read exactly.

You're storingUseWhy
Code snippets, configs, generated SQLarchive()One changed character breaks it
Legal text, exact user quotesarchive()Must be reproduced verbatim
Insights, preferences, patternsSemantic entries (remember())Should generalize, reconcile, and rank by relevance
A working artifact and the knowledge around itBoth — archive, then a semantic entry referencing the idExact recovery plus similarity-retrievable context

Walkthrough

At Nimbus, Ari finally lands the batched-exporter config that fixes Acme Corp's CSV-export timeouts. The config must survive byte-for-byte; the insight about when to apply it should be semantic so it surfaces on the next similar ticket:

archived = client.archive(
    session_id="nimbus:ari:ticket-1042",
    content=exporter_config_text,        # the exact config that worked
    artifact_kind="config",
    labels=["csv-export", "acme"],
    metadata={"verified_on": "TCK-1042"},
)
ref = archived["reference_id"]
 
# The semantic half: a lesson that points at the exact artifact.
client.remember(
    content=(
        "When an Acme CSV export times out on large reports, apply the batched "
        f"exporter config archived as {ref} — dereference it, never retype it."
    ),
    intent="lesson",
    lesson_type="success",
    share="session",
    metadata={"reference_id": ref},
)
 
# Any later run in scope recovers the artifact exactly:
exact = client.dereference(session_id=run_id, reference_id=ref)
if exact.get("found"):
    config_text = exact["evidence"]["content"]   # byte-for-byte

The combination is the point. The next timeout ticket retrieves the lesson semantically (a differently-worded query still matches), and the lesson hands the agent a reference_id it can dereference for the config with zero paraphrase risk.

ℹ️Note

archive() requires the archive_block write scope and dereference() the matching read scope — register agents with both if they round-trip artifacts. See Exact references.

When not to use it

Don't archive everything. Archived blocks are immutable and sit outside the learning loop — they are never reconciled, superseded, or promoted the way semantic entries are, so knowledge that should evolve (preferences, patterns, lessons) belongs in semantic entries. Archive is for artifacts where fidelity beats adaptability.

Related