Documents Are Memories Too: The Claude-Markdown-File Pattern in a Governed System

AI agents need a place to write sectioned markdown notes they can later read, append, or rewrite. The same shape Claude uses for its memory files, but inside a governance and retrieval layer that everything else uses. When to save as a document, how the section-update pattern works, and what flipping the aiExtraction switch does to your modality picture.

Claude keeps notes the way humans keep notes

If you have watched Claude work for any length of time, you have seen it write to a markdown file. A NOTES.md it appends to as it learns about a project. A DECISIONS.md it updates when something gets resolved. A MEMORY.md it sections by topic and rewrites in place when a section becomes stale.

The pattern is not coincidental. Markdown is what humans use to take notes. Sections give knowledge structure that survives revisions. Append-only growth is what you want when you are building knowledge over time. Section-level rewrites are what you want when you discover that what you wrote two weeks ago is now wrong about one specific topic, but still right about everything else.

For an agent to be useful as a teammate, it needs the same shape. A place where it can write, read its own writing, append, and revise, without losing context, without re-writing the whole world to fix one sentence, without flattening structure into a wall of prose.

In Personize this lives at context/save. The endpoint accepts a markdown body, a type (guideline, playbook, reference, template, brief, or a custom org-defined type), and one of four update modes that map directly to how Claude updates its own memory files. The result is a stored document that the agent can read back through the same unified retrieve as memories and properties, with the same governance, the same identity model, and the same graph fan-out.

This article is about when to use the document modality, how the update modes work, and what changes when you flip on aiExtraction.

The shape of a document

A document save is one call.

{
  "name": "acme-deal-review-2026q2",
  "type": "brief",
  "value": "# Acme Q2 Deal Review\n\n## Background\nAcme is evaluating Personize for governed agent memory. The CTO, Jane, drove vendor selection.\n\n## Stakeholders\n- Jane (CTO, jane@acme.com)\n- Marcus (CFO, marcus@acme.com)\n\n## Open Risks\n- API rate limits for their daily extraction batch\n- Vendor consolidation policy in their procurement team\n\n## Next Steps\n- Discovery call with Marcus on June 12\n",
  "updateMode": "replace"
}

Notable fields:

• name is the addressable handle. Subsequent updates can refer to the doc by name.
• type is one of a small set of governed types: guideline (policy), playbook (how-to), reference (lookup material), template (form), brief (situation-specific writeup). Custom org-defined types are accepted.
• value is the markdown body. Headings define sections. Inline links and code blocks behave the way you would expect.
• updateMode controls how a subsequent save with the same name merges with the existing content.

The body is stored as markdown in S3, with metadata in PostgreSQL. The retrieval layer chunks it semantically and ranks chunks alongside memories and documents from other sources. Citations point at the doc by ID, with the heading and section captured in the chunk metadata so an agent can cite "from the Open Risks section of the Acme Q2 brief" instead of "from a paragraph that mentioned vendor consolidation."

The four update modes

The update mode is where the document modality earns its keep. An agent that has to rewrite the entire document every time it learns something new is going to either lose information or stop writing. The four modes correspond directly to the operations Claude performs against its own memory files.

replace: overwrite the whole document. Use when the existing body is wrong enough that a clean rewrite is better than patching, or when the agent has composed a fresh version from new inputs.

section: replace one section by heading. The body matches a ## Heading in the existing doc; the new content replaces what was under that heading. Other sections are untouched. Use when one specific area got resolved or updated and the rest of the doc is still right.

append: append at the end of the doc. Use when adding a new section or chronologically extending a log-style document.

appendToSection: append inside a specific section without disturbing the rest. Use when adding bullet points to an existing list, or new evidence to an "open risks" section, or a new entry to a chronology under its date heading.

Here is a sequence of saves against the same doc that shows how the modes compose:

// Initial save: full body
{ "name": "acme-q2-brief", "value": "# Acme Q2\n## Stakeholders\n...\n## Risks\n- A\n", "updateMode": "replace" }
 
// Two weeks later: add a stakeholder, do not rewrite the rest
{ "name": "acme-q2-brief",
  "value": "## Stakeholders\n- Jane (CTO)\n- Marcus (CFO)\n- Sasha (VP Procurement)\n",
  "updateMode": "section" }
 
// One week later: a new risk surfaced
{ "name": "acme-q2-brief",
  "value": "- API rate limits for daily extraction batch\n",
  "updateMode": "appendToSection",
  "section": "Risks" }
 
// Quarter ends: log the close
{ "name": "acme-q2-brief",
  "value": "\n## Outcome\nClosed-won on June 28. ARR: $1.2M.\n",
  "updateMode": "append" }

Each save is a few hundred tokens. The doc accumulates structure over time without the agent having to read and rewrite the whole body on every update. The agent works at the granularity of "the thing I learned just now" instead of "the whole document I was going to maintain."

When this is the right pattern

The document modality is the right shape when the unit of knowledge is bigger than a fact, smaller than a database, and intended to be read by humans or agents who want structure.

Running deal reviews. An account brief that gets updated as discovery, demo, negotiation, and close progress. Each phase appends to its section. The whole doc is the artifact a salesperson hands to their manager.

Living playbooks. "How we handle vendor consolidation conversations." Updated whenever an objection or counter is refined. The agent that drafts replies cites the playbook section it followed.

Audit trails. "What the agent did, in order, with what context." Append-only by design. Sections per day or per incident. The doc is the artifact the compliance team reviews.

Reference docs. "Personize API authentication patterns." Cited across many records. Updated when the API changes. The retrieval surface chunks it and returns the right section for the agent's current question.

Briefs for situations. "Q2 2026 strategic priorities." Written once, occasionally updated, referenced by many downstream agents that need to know what the company is focused on.

The modality is the wrong shape when the unit is a single fact (atomic memory), a typed value on a record (typed property), or a binary asset (use the attachment system). It is also wrong when the content is genuinely ephemeral, chat history that nobody will read again does not belong in a document.

The aiExtraction toggle

Here is where document save crosses back into the other modalities.

{
  "name": "acme-q2-brief",
  "type": "brief",
  "value": "# Acme Q2 Deal Review\n\n## Background\nAcme is evaluating Personize. CTO Jane (jane@acme.com) drove vendor selection.\n\n## Open Risks\n- API rate limits...\n",
  "aiExtraction": true
}

With aiExtraction: true, the markdown body is also extraction input. The same extractor that runs on memory/save runs on the document body. The doc is saved as a document. The atomic memories pulled from the body are also saved as atomic memories. The typed property values surfaced in the body are also saved as properties.

One call. One LLM cost. Three storage shapes.

For an agent maintaining a sectioned playbook that should also surface its key facts semantically and update the relevant record properties as it writes, this is the right shape. The agent writes prose. The system extracts what is structurable. The retrieval surface gets clean access to all three modalities, served from one source of truth.

The default for aiExtraction is off, for a reason. Most documents the customer saves do not need to feed back into the memory layer, a guideline doc is meant to be read as a doc, not chunked into atomic facts. Forcing extraction on every save would burn tokens on content where the extraction has no consumer.

The customer turns it on when the document has factual content worth surfacing through atomic memory and property channels. The classic case is an account brief whose body mentions specific people, specific roles, specific signals, all of which are also worth landing as memories about those records.

What this does to the graph

Document writes can also drive graph edges, through the same three-channel pattern covered in The Three Channels of Graph Writes. The fields are renamed on the document side but the mechanics are identical.

Layer A, recordIds. When the save call includes recordIds: ["REC#JANE", "REC#MARCUS"], the system writes typed doc-to-record links automatically. The doc becomes findable from each linked record's retrieve call as part of the documents source.

Layer B, relations. When the save call includes a relations[] array, record-to-record edges get written from the doc save call. The doc itself is the evidence.

Layer C, extractEntities. When the save call includes extractEntities: true, an LLM reads the body and proposes edges to entities with strong identifiers (emails, domains, phones). The doc is the evidence for each edge.

The three layers are independent. A single doc save can use any subset. When the doc gets deleted later, edges that had only this doc as evidence get garbage-collected. Edges that had multiple evidence documents remain, with this doc removed from their evidence list.

The agent that writes a "what we know about Acme" doc with extractEntities: true ends up with a connected graph from the doc to the entities it mentions, queryable through the same graph source that record-write edges use. The graph layer does not know or care that the edge originated from a document save instead of a memorize call. It sees the edge, the source (document_extraction), and the evidence document IDs.

When the agent should use which save endpoint

Two endpoints. One decision.

memory/save when the input is content the agent received from outside and needs to remember. A transcript, an email, a CRM record sync. The extractor pulls atomic memories and typed properties from it. Optionally writes graph edges through the three channels. The content body itself is not the storage target; the extracted memories and properties are.

context/save when the agent itself is authoring the content. A deal review the agent composed. A playbook update the agent revised. A brief the agent assembled from multiple sources. The body is the storage target; it is going to be read back as a document. Add aiExtraction: true if you want the body to also feed the memory and property channels.

The two endpoints are not interchangeable, but they compose. An agent that reads a transcript through memory/save (which produces twelve atomic memories and updates four typed properties) might then compose a "summary of what we learned" doc and save it through context/save (which preserves the summary as a readable artifact and, if aiExtraction: true, surfaces its key facts as atomic memories too).

The summary doc is not a duplicate of the transcript memories. It is a different shape of the same knowledge, optimized for human and agent reading instead of for retrieval-by-similarity. Both shapes exist. Both are retrievable. The agent or human consuming downstream decides which shape they need.

The principle

The market keeps reaching for "files for agents" because the markdown-file pattern is genuinely the right shape for the kind of memory an agent wants to maintain over time. The hard part is not the storage; it is making the file behave the way a governed system needs it to behave, versioned, governed by org policy, retrievable through the same surface as everything else, optionally feeding back into the structured memory layer.

context/save is that pattern, with the four update modes that make sectioned authoring actually work, with the type system that puts the doc in a governance lane, with the optional aiExtraction that lets the doc body serve double duty as memory content, and with the same three-channel graph fan-out as record writes.

If you are building agent memory and your current pattern is "the agent writes to a database column and we hope the prose is parseable," consider the document modality instead. Pick the type. Pick the update mode. Optionally turn on extraction. The same governance and retrieval surface that handles your memories and properties handles your notes too.

Companion pieces: Three Modalities, One Save Surface covers the broader modality picture. The Three Channels of Graph Writes covers the graph fan-out from document saves. One Call, Four Sources covers the retrieval payload that includes documents as one of the four sources.