Memory fragments

A memory fragment is the basic unit of knowledge in Usable. It is a readable Markdown document with a title and supporting information such as a summary, tags, a fragment type, and optional files.

Fragments are meant to stand on their own. A person should be able to open one and understand the topic, while a search or AI agent should be able to recognize when that fragment is relevant.

The anatomy of a fragment

A typical fragment includes:

• a title that names the topic clearly;
• content written in Markdown;
• a fragment type that describes what kind of knowledge it contains;
• a short summary for scanning and retrieval;
• tags for useful labels and filters;
• platform metadata such as workspace, author, and timestamps;
• optional collection membership, a stable key, and attached files.

Not every fragment needs every optional field. The title and content should still explain the subject without relying on tags or collection names for missing context.

One useful topic at a time

The best fragment size is not measured by word count. A fragment is well scoped when it answers one recognizable need.

For example, “Deploy the service to production” can be a focused Recipe. Combining deployment, local setup, architecture history, incident notes, and every configuration option into one fragment makes the material harder to maintain and retrieve.

At the other extreme, splitting every sentence into a separate fragment removes the context readers need. Keep concepts together when they are normally understood or applied together.

A useful test is: Would someone search for this topic by itself, and would this fragment give them enough information to act or learn?

Markdown content

Fragment content supports Markdown, so you can structure explanations with headings, lists, links, tables, and code examples. Use structure to help readers navigate—not to avoid writing connective prose.

A good fragment usually starts with a short explanation of what the topic is and why it matters. Procedures should state prerequisites before the steps. Technical examples should explain what the reader is expected to change.

Lifecycle and status

Fragments have a platform lifecycle. Depending on the interface and workflow, you may encounter active, stale, or archived material, as well as publishing conventions used by a particular workspace.

Treat status as a signal about whether a fragment should be used, not as a substitute for maintaining the content. Archive material that should no longer appear in normal workflows. When behavior changes, update the existing source when readers expect continuity rather than creating an unexplained duplicate.

Some publishing integrations also read frontmatter such as status: published. That is content metadata interpreted by the integration; it is distinct from the fragment’s platform lifecycle.

Stable keys

A fragment can have a workspace-scoped key, such as api-authentication-guide. Keys provide a readable, stable identifier for integrations that should not depend on a title. A key must be unique within its workspace.

Use keys for configuration fragments, recurring automation targets, or documents addressed programmatically. Do not treat a key as a substitute for a clear title.

Files and attachments

A file can be attached to a fragment when it supplies evidence or supporting material—a diagram, PDF, screenshot, or report. The fragment should explain why the file matters and remain useful even if the reader cannot open the attachment.

Avoid storing secrets or unreviewed customer data in files, especially in public workspaces.

Example: turning a discovery into durable knowledge

After solving a recurring authentication failure, write a Solution fragment with:

1. a title naming the visible error;
2. a short explanation of the cause;
3. the verified fix and how to confirm it;
4. boundaries or cases where the fix does not apply;
5. tags for the affected product and authentication area.

That fragment is more useful than a pasted chat log because future readers can quickly recognize the problem and trust the documented resolution.

Good practices

• Use specific titles that match how someone would describe the topic.
• Explain context before details or steps.
• Keep one clear purpose per fragment.
• Prefer maintained sources over near-duplicates.
• Write an informative summary and a small set of meaningful tags.
• Attach source material only when it adds value.
• Remove secrets, private URLs, and sensitive data before sharing.

Related concepts

• Fragment types describe the role a fragment plays.
• Frontmatter and metadata explains information stored alongside the body.
• Tags and summaries covers the signals that make fragments easier to scan and retrieve.