RememberStackremember.dev/docs

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 list
curl -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:value convention (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-Migration finds project:billing-migration, and registering both is refused with 409 conflict.
  • 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 409 tag_limit_exceeded and 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:decision

Over 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 tag
remember 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"]}'
  • set replaces the whole set and cannot be combined with add or remove; an empty set removes 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 (404 document_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:

ListKeeps a document that carries
allevery listed tag
anyat least one listed tag
nonenone 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:draft
curl -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 tags combines with the other document filters with AND, so family: ["email"] plus tags: {"all": ["project:billing-migration"]} finds the billing migration's emails.
  • A document without tags passes a none list and fails all and any.
  • A tag that is not registered refuses the whole search with 422 unknown_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 time reads the editions in force then, chosen by the tags the document carries now.
  • The filter is applied while ranking, so k: 10 returns 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-migration
curl -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_context returns only claims and passages from tagged documents: what those documents said.
  • facts_context returns 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. Each evidence_totals entry keeps its count across all documents and adds in_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_ids as 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:draft

A 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 /documents and each result of POST /documents/search has tags: the document's tag names, ordered by name.

  • SQL queries. tags_current has one row per registered tag, and document_tags_live one row per tag on a live document, with the tag's current name. A chunk inherits its document's tags through doc_id, a claim through its occurrences, and a fact through its supporting claims. The shipped saved query examples.facts_by_tag lists 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_tag and update_document_tags; ingest takes tags, search_documents takes a tags filter, and the three context tools take documents. 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.