Tag documents
Dana's deployment holds the work of several projects: the billing migration's specs and decision records, the support team's meeting notes, John's engineering design documents. The memory is shared on purpose, because the same people, systems and decisions turn up in all of them. Dana still wants to say which documents belong to which body of work, so that she and the agents she works with can see it at a glance.
Tags do that. A tag is a name, such as project:billing-migration, with a
description of what it means. You register a tag once, then assign it to the
documents it applies to. A document can carry several tags. This guide shows
how to register, assign, change and remove tags, how to search and ask
about only the documents that carry them, and where they show up.
Setup is in the Quickstart. The routes are in Ingest, readiness and documents.
Register a tag
A tag must be registered before any document can carry it. That keeps the
vocabulary in one place: anyone, person or agent, can list the tags and read
what each means instead of guessing between project:billing-migration and
proj:billing. A tag that is not registered is refused, so a typo is an
error rather than a silently untagged document.
from remember import Client
memory = Client()
memory.create_tag(
name="project:billing-migration",
description="Documents about moving invoicing to the new billing provider: specs, decisions and meeting notes.",
)
memory.create_tag(name="kind:decision", description="An accepted decision record, not a proposal.")remember tags create kind:draft --description "A proposal that is not decided yet."
remember tags listcurl -s -X POST "$REMEMBER_API_URL/tags" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "project:support", "description": "Support team notes and tickets."}'The rules for a tag:
- Name. 1 to 128 characters after Unicode NFC normalization, with no
whitespace or control characters. The engine gives a name no structure;
a
key:valueconvention (project:…,kind:…,source:…) keeps a shared memory readable. - Spelling and case. A name keeps the spelling you declare, and names
are unique ignoring letter case:
Project:Billing-Migrationfindsproject:billing-migration, and registering both is refused with409conflict. - Description. Up to 2,000 characters. Write it for the agent that will choose the tag later: what the tag means and when to apply it.
- Limits. A deployment registers at most 10,000 tags, and a document
carries at most 64. A write past either is refused with
409tag_limit_exceededand changes nothing.
Wherever a call takes a tag, it accepts the name in any letter case or the
tag_id.
Tag a document when you ingest it
Pass tags with the upload. The tags are added to the document's tags.
version = memory.ingest(
"specs/billing-migration.md",
source_kind="notes",
source_ref="specs/billing-migration.md",
tags=["project:billing-migration"],
)remember ingest decisions/0007-invoice-cutover.md \
--source-kind decisions --source-ref billing/0007 \
--tag project:billing-migration --tag kind:decisionOver HTTP, repeat the tags query parameter:
POST /ingest?filename=…&mime=…&tags=project:billing-migration&tags=kind:decision.
Ingest only adds tags. A tag the document already carries stays, and
leaving tags out removes nothing. This matters because one document can be
reached by more than one caller: when John and Dana upload the same file
for two different projects, both reach the same document, and it ends up
with both projects' tags.
Tags never decide whether a version is created. Sending a file identical to
the latest version, with new tags, adds the tags and is still a no-op
("created": false). Tags are not part of what the engine processes, so
adding them starts no work.
If any tag is not registered, the whole ingest is refused with 422
unknown_tag, naming every unregistered tag, and nothing is stored. The
Python client raises remember.UnknownTag, whose tags lists them.
Change a document's tags
update_document_tags adds and removes tags, or replaces the whole set, in
one step, and returns the document's tags afterwards.
memory.update_document_tags(doc_id=version.doc_id, add=["kind:decision"], remove=["kind:draft"])
memory.update_document_tags(doc_id=version.doc_id, set=["project:billing-migration"])
memory.update_document_tags(doc_id=version.doc_id, set=[]) # removes every tagremember documents tag a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b --add kind:decision --remove kind:draft
remember documents tag a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b --set ''curl -s -X POST "$REMEMBER_API_URL/documents/a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b/tags" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"set": ["project:billing-migration", "kind:decision"]}'setreplaces the whole set and cannot be combined withaddorremove; an emptysetremoves every tag.- Removing a tag the document does not carry is not an error, as long as the tag is registered.
- Every tag named must be registered; otherwise nothing changes and the
call is refused with
unknown_tag. - A deleted document cannot be tagged (
404document_not_found).
Tags belong to the document, not to one version: every version, old and new, carries the document's current tags. Changing them never reprocesses the document or creates a version.
To retag many documents, find them with
search_documents
and update each one; there is no bulk retag.
Search only tagged documents
Claim search, chunk search and search_documents take a tags selector in
their document filter: documents on
POST /search/claims and POST /search/chunks,
filters on
POST /documents/search.
It has three lists, each of tag names (any letter case) or ids:
| List | Keeps a document that carries |
|---|---|
all | every listed tag |
any | at least one listed tag |
none | none of the listed tags |
from remember import DocumentSearchFilters, DocumentTagFilter
billing = DocumentSearchFilters(tags=DocumentTagFilter(all=("project:billing-migration",)))
claims = memory.search_claims(query="invoice cutover date", documents=billing)
decided = memory.search_documents(
filters=DocumentSearchFilters(
tags=DocumentTagFilter(all=("kind:decision",), any=("project:billing", "project:support"))
)
)remember documents search --tag kind:decision --not-tag kind:draftcurl -s -X POST "$REMEMBER_API_URL/search/chunks" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "invoice cutover", "documents": {"tags": {"none": ["kind:draft"]}}}'- The lists combine with AND, and
tagscombines with the other document filters with AND, sofamily: ["email"]plustags: {"all": ["project:billing-migration"]}finds the billing migration's emails. - A document without tags passes a
nonelist and failsallandany. - A tag that is not registered refuses the whole search with
422unknown_tag, naming every one, so a typo never looks like an empty answer. Give at least one non-empty list; a list holds up to 32 tags and may not name a tag twice. - A document's tags apply to all its versions. A search with a past
timereads the editions in force then, chosen by the tags the document carries now. - The filter is applied while ranking, so
k: 10returns up to ten results from tagged documents even when untagged documents score higher. - When a filtered search finds nothing, its explanation says whether no live document carries the tags or the tagged documents say nothing relevant to the query.
Tags only choose which documents a search reads. They never change what the memory extracted or believes.
Ask about one project
The context operations an agent uses most, facts_context,
claims_and_sources_context and combined_context, take the same filter as
documents. Dana's agent, working on the billing migration, asks only what
that project's documents say:
billing = {"tags": {"all": ["project:billing-migration"]}}
facts = memory.facts_context("When is the invoice cutover?", documents=billing)
said = memory.claims_and_sources_context("invoice cutover", documents=billing)
both = memory.combined_context("invoice cutover risks", documents=billing)remember query "When is the invoice cutover?" --tag project:billing-migrationcurl -s -X POST "$REMEMBER_API_URL/operations/facts_context" \
-H "Authorization: Bearer $REMEMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "When is the invoice cutover?",
"documents": {"tags": {"all": ["project:billing-migration"]}}}'claims_and_sources_contextreturns only claims and passages from tagged documents: what those documents said.facts_contextreturns the facts the tagged documents support, and their supporting evidence comes only from those documents. The memory's answer is not narrowed, though: if the support team's notes say the cutover is a week later, that note comes back as contradicting evidence marked"in_documents_filter": false, and the competing fact comes back in the fact's contradiction, marked the same way. Eachevidence_totalsentry keeps its count across all documents and addsin_documents_filter_total. A filtered answer never looks more certain than the memory is.- A fact's value, validity and support are the memory's, the same as in an unfiltered read.
- With
entity_idsas well, a result must be about one of those entities and come from a tagged document.
Agents connected over MCP get the same documents argument on the three
tools; their descriptions tell them to call list_tags first. The whole
contract is in
The documents filter.
Rename, re-describe or delete a tag
memory.update_tag(tag="project:billing-migration", name="project:billing")
memory.update_tag(tag="project:billing", description="Everything about the billing provider change.")
memory.delete_tag(tag="kind:draft")remember tags update project:billing --description "Everything about the billing provider change."
remember tags delete kind:draftA rename changes one record: every document that carries the tag shows the
new name at once. There are no aliases, so the old name stops working, and a
call that still uses it gets unknown_tag. Deleting a tag removes it from
every document that carries it, in one step; the documents themselves are
unchanged. Over HTTP, PATCH and DELETE /tags/{tag_id} take the tag's id,
because a name may contain /; the client, the CLI and the MCP tools accept
the name and look the id up.
Where tags show up
-
Document lists and search. Each item of
GET /documentsand each result ofPOST /documents/searchhastags: the document's tag names, ordered by name. -
SQL queries.
tags_currenthas one row per registered tag, anddocument_tags_liveone row per tag on a live document, with the tag's currentname. A chunk inherits its document's tags throughdoc_id, a claim through its occurrences, and a fact through its supporting claims. The shipped saved queryexamples.facts_by_taglists the current facts supported by documents that carry a tag:curl -s -X POST "$REMEMBER_API_URL/query/saved/examples/facts_by_tag/run" \ -H "Authorization: Bearer $REMEMBER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"parameters": ["project:billing-migration"]}' -
MCP. Agents get the tools
list_tags,create_tag,update_tag,delete_tagandupdate_document_tags;ingesttakestags,search_documentstakes atagsfilter, and the three context tools takedocuments. See MCP tools.
Tags and deleted documents
A deleted document never shows its tags: it leaves GET /documents, search
and the SQL views, and its tags with it. The engine keeps the record of which
tags it carried, so if you ingest the document again it comes back with
those tags. Forgetting a document (the operator's hard forget) removes that
record; the registered tags themselves stay, because they are the
deployment's vocabulary, not content from any document.
What tags are not
- Not part of the memory's content. A tag is never extracted, resolved or turned into an entity or fact, and tagging a document cannot change a claim extracted from it or a fact it supports.
- Not a way to split the memory. Entities, claims and facts stay shared across every tag. Bodies of work that must never share entities or facts belong in separate deployments.
- Not metadata about the source. Authors, dates and titles are what a file declares about itself; tags are how you organize it.