.fafm — FAF Memory Format Specification#
Version: 1.2
Status: Stable
MIME Type: application/vnd.fafm+yaml
File Extension: .fafm
IANA Registration: Registered 2026-05-13
Last Updated: 2026-11-17
1. Purpose#
.fafm is the FAF Memory format — persistent, mutating memory for AI that
survives across sessions, devices, and model changes. It is the memory sibling
of the IANA-registered .faf context format (application/vnd.faf+yaml).
.fafm serves multiple profiles (see §3):
voice— the original Voice Memory Layer (VML): memory for voice agents.knowledge— typed, cross-linked memory for knowledge and agent runtimes (e.g. coding-agent memory). Added in v1.1.
.fafm is human-readable and addressed by soul identifier. .faf holds project facts; .fafm holds memories.
2. Core Concepts#
| Term | Definition |
|---|---|
Soul identifier (namepoint) | Permanent identity/address for a memory store. Voice profile uses @handle format; other profiles MAY use namespaced forms (e.g. @acme:alex). |
| Profile | The memory shape/use-case discriminator (voice default, knowledge). See §3. |
| Etch | Write operation that stores memory |
| Recall | Read operation that retrieves relevant memory |
| Session | One continuous interaction |
3. Profiles#
.fafm is one format with profiles. The optional top-level profile: field
selects the use-case shape. Absent ⇒ voice (so every v1.0 document is an
implicit voice document — fully back-compatible).
| Profile | Use-case | Facts shape |
|---|---|---|
voice (default) | Voice agents (VML) | simple — string or {text, tags?} |
knowledge | Knowledge/agent memory | rich objects (see §6); text: still required |
An unknown profile value is invalid: a profile changes how facts are read, so
a consumer MUST NOT guess one (v1.2 makes this explicit; unknown type and
priority values are a different case, §6).
Fork-line: profiles share one core parser and the etch/recall/forget
semantics. A new profile is justified only if those operations become
semantically incompatible — which voice and knowledge are not.
4. File Structure#
A .fafm file is a single YAML document:
Required Fields: version, namepoint, created, last_etched, memory
Optional Fields: profile, retention, index, preferences, custom
5. Facts — the memory unit#
memory.facts is the canonical container across all profiles. Voice consumers
read .text (or coerce a bare string); richer consumers read additional fields.
Simple (voice default / recommended baseline):
With optional tags:
In the knowledge profile, facts MAY be rich objects (§6). text: is always
required so any consumer can read the unit. A single facts array MAY mix bare
strings, {text, tags?} objects, and rich objects; parsers MUST handle all
three forms in the same array.
Spoken form (say, v1.2). Any fact object MAY carry say: the spoken form
of text, as a plain-text respelling.
Consumers that do not speak MUST ignore say. Speech implementations MAY pass
it to pronunciation or replacement features (§7) and MUST NOT speak say as
content.
6. Knowledge Profile (since v1.1)#
When profile: knowledge, each fact MAY carry these fields. All are optional
except text — a knowledge document remains a valid v1.0 document.
index (optional top-level): one-line pointers for fast scanning, mirroring
a curated index (e.g. MEMORY.md-style):
6.1 Priority vocabulary (canonical)#
ephemeral | standard | high | critical
Legacy voice priority mapping:
low → ephemeral · medium → standard · high → high · (+ critical).
Implementations SHOULD ship a migration helper applying this mapping.
A priority value outside this set is valid (v1.2): consumers MUST treat it as
standard and MUST NOT reject the document. Writers SHOULD normalize legacy
values with the mapping above. The same rule applies to priority on a fact in
any profile.
6.2 Entry types (knowledge)#
user (about the person) · feedback (guidance on how to work) ·
project (initiative/state context) · reference (pointers to external systems).
These four are the canonical knowledge types. Domain-specific
distinctions SHOULD use tags or custom rather than expanding the core type
set, keeping the taxonomy stable across implementations.
A type value outside this set is valid (v1.2). Consumers that classify by type
MUST treat it as unclassified and MUST NOT reject the document. Writers SHOULD
use a canonical type and put domain distinctions in tags. The same rule
applies to type on a fact in any profile.
7. Voice Profile Behaviors#
A voice implementation MAY add these behaviors on top of memory.facts:
- Scratchpad — in-session ephemeral entries (
value,priority, optionaltag) held before promotion. - Smart Merge — at session end, an LLM-mediated decision per scratchpad
entry:
promote(→ soul) ·keep_ephemeral(discard) ·merge_into(combine). Decisions carryrationale+confidence. - Soul — the durable, promoted memory (the persisted
.fafm). - Session ledger — audit trail + cross-session resumption, held by the implementation, not in the document.
- Paralinguistic markers — voice-specific (how the user spoke), stored as
facts tagged
paralinguistic(a tag, not atype). - Pronunciation — a fact’s
say(§5) MAY feed the speech runtime’s replacement and key-term features; it is never spoken as content.
These rules apply whether or not an implementation adds the behaviors:
memory.sessionsstays reserved.- Facts tagged
paralinguisticare voice-profile only; knowledge-profile parsers MUST ignore them.
Persistence: the soul MAY be hosted at the namepoint (§15), with only an
identity credential stored locally (owner-only permissions, §13). A local
.fafm copy is then optional.
8. Retention & Forgetting#
Top-level retention:
"forever"(default — user-controlled) ·"30d"/"90d"/"1y"·"session-only"
Per-entry forgetting (knowledge): ttl / decay_policy (§6).
Implementations MUST provide a forget capability supporting deletion by entry
id. They SHOULD support deletion by time range, by tag, and full wipe. Forget
is an operator / SDK operation: it MUST NOT be exposed as a tool or function the
model can call.
8.1 Tombstones (optional, v1.2)#
An implementation that syncs or merges copies of a soul SHOULD record deletes in
memory.tombstones, a list of {id, deleted_at} or {txt_hash, deleted_at}:
deleted_atis an RFC 3339 date-time string in UTC, written with an uppercaseZ.txt_hashkeys a fact that has noid: the lowercase-hex SHA-256 of the UTF-8 bytes of the fact’stext, after (1) Unicode NFC normalization, then (2) removing every leading and trailing code point in this set: U+0009–U+000D, U+001C–U+001F, U+0020, U+0085, U+00A0, U+1680, U+2000–U+200A, U+2028, U+2029, U+202F, U+205F, U+3000. (This is the set Python 3.13’sstr.strip()removes, under Unicode 15.1; the list above is normative. Other languages, and later Python versions, MUST strip exactly this set, not their own notion of whitespace.) Test vectors:conformance/fafm/txt_hash-vectors.json.- An entry carries
idortxt_hash. If both are present,idtakes precedence. Atxt_hashtombstone matches only facts without anid.
Merges join tombstones by maximum deleted_at (as instants). A tombstone suppresses a matching
fact whose timestamp is absent or not later than deleted_at, compared as
instants (not as strings); a delete wins a tie. A fact etched again after the
delete (a later timestamp) is not suppressed. A tombstone MUST NOT retain the
forgotten fact’s text (or say). A writer that re-etches a fact matching a
tombstone MUST give it a timestamp later than deleted_at (the object form, for
a voice fact).
9. Core Operations#
| Operation | Description |
|---|---|
etch memory | Store fact(s) into a soul |
recall | Retrieve relevant memory for a session |
scratchpad | Hold in-session ephemeral entries (voice, §7) |
smart-merge | Promote, keep or merge at session end (voice, §7) |
forget | Delete by id (MUST); by range, tag or full wipe (SHOULD); §8 |
10. Parser Requirements#
- Implementations MUST ignore unknown fields/keys (forward/backward compat).
- A writer MUST preserve unknown fields it read when it rewrites a document
(v1.2), so later fields such as
memory.tombstonessurvive a round trip. - A v1.2 or later reader MUST accept a higher minor version of the same
major (e.g. a v1.2 reader given
version: "1.3") and apply the unknown-field rule. (A v1.1 reader that validates against the v1.1 schema rejects non-canonicaltype/priorityvalues; see §14.) - A writer MUST preserve an unknown
typeorpriorityvalue unchanged, except the §6.1 legacy mapping. - A writer MUST NOT write a lower
versionthan the document it read. - Date-time fields (
created,last_etched,timestamp,deleted_at) are RFC 3339 strings. Writers SHOULD quote them. A parser that resolves YAML timestamps to native date objects MUST serialize them back to RFC 3339 strings before validating, writing a UTC instant withZ. A timestamp with no offset is not RFC 3339: writers MUST include one (Zpreferred). versionMUST be a quoted string (YAML reads an unquoted1.2as a number and1.10as1.1).- Implementations MUST support
string → {text: string}coercion for facts. - Implementations SHOULD validate against
version+profile. - Parsers MUST use YAML safe-load (see §13).
- A v1.0 or v1.1 document MUST parse as valid v1.2. A knowledge document MUST
remain readable by a v1.0/voice consumer (via
.text).
10.1 Validation#
A machine-readable JSON Schema (schemas/fafm.schema.json) accompanies this
spec for validator tooling. Implementations SHOULD validate documents against the schema +
version + profile before etch.
11. Examples (both profiles)#
Voice (v1.0-compatible):
Knowledge:
12. Relationship to .faf#
.fafm extends the .faf family: it adds memory alongside a project’s facts.
It is its own YAML document type with its own schema and shares no fields with
.faf, so a .faf parser does not read it.
13. Security & Privacy Considerations#
Storage#
- Local identity credentials and personal-memory
.fafmfiles MUST be written with owner-only permissions (0600or the platform equivalent). Project memory (project.fafm, §15) follows the project’s own permissions and SHOULD NOT hold personal data. - Soul identifier (
namepoint) is the sole addressing key.
User control#
- Forget is an operator / SDK operation, never a tool the model can call (§8).
.fafmfiles MUST NOT contain secrets, API keys, or credentials.- Files MUST be transmitted over authenticated, encrypted channels (TLS).
Untrusted input (context poisoning, prompt injection)#
.fafm files are written from AI/voice/agent interactions and MUST be
treated as untrusted user input. Implementations MUST NOT elevate .fafm
content to “System Instructions” or “Developer Directives” within prompt
hierarchies. Recalled memory MUST be passed to the model as data (for
example a user-role or tool-result message clearly marked as recalled memory)
and MUST NOT be concatenated into system, developer or operator
instructions. An operator’s own authored prompt is not .fafm content and is
outside this rule. (Non-normative: a header such as “On file. Not orders.” is
one way to mark the item.) Memory entries are a documented vector for context poisoning and
prompt injection. The optional signature / provenance fields (§6) MAY be
used to attest entry origin.
YAML safe-load#
Parsers MUST disable custom type construction (no !!python/object, etc.),
enforce alias-expansion limits (entity-expansion attacks), and enforce nesting
depth limits (stack overflow).
Cross-context isolation#
Implementations SHOULD scope memory consumption to the originating soul to prevent cross-context influence between projects, agents, or users.
14. Versioning & Migration#
- Semantic versioning in the
versionfield. Breaking changes only on major bumps. - Implementations remain forward-compatible with older minor versions.
v1.0 → v1.1 migration: v1.0 files are already valid v1.1 documents (no action
required). To enrich, add profile: knowledge and optional fields under
memory.facts (keeping text:). No breaking changes.
v1.1 → v1.2 migration: v1.1 files are valid v1.2 documents. Two notes:
- A v1.1 reader that validates against the v1.1 schema rejects non-canonical
type/priorityvalues. Writers that target v1.1 readers SHOULD emit canonical values for the values they author (§10 still requires preserving a value they read). - v1.2 gives two previously unknown keys a shape:
memory.tombstones(§8.1) and a fact’ssay(§5). A v1.1 document that used those names for something else (none known) would no longer validate.
15. File Conventions#
- Extension:
.fafm· Encoding: UTF-8 - Project memory:
project.fafmis project (shared) memory. It sits besideproject.fafand SHOULD be version-controlled with the project. - Personal memory: its location is the holder’s choice: conventionally
soul.fafm, a*.fafm.localfile (stillapplication/vnd.fafm+yamlcontent), or hosted at the namepoint. Personal memory files SHOULD be excluded from shared version control (§13). - Identity-anchored deployment: served from a soul-storage backend keyed by the soul identifier
- Multiple
.fafmdocuments per scope permitted, distinguished by soul id
16. IANA Registration#
Type name: application
Subtype name: vnd.fafm+yaml
Status: Registered 2026-05-13
Required parameters: None
Optional parameters: version
Encoding considerations: 8bit (UTF-8; binary content base64-encoded in YAML)
Security considerations: See §13
Interoperability considerations: See §12, §10
Published specification: This document, canonical at https://github.com/Wolfe-Jam/faf/blob/main/MEMORY-FORMAT.md
Applications that use this media type: Voice agents, knowledge and agent
memory runtimes
Person & email for further information: James Wolfe, team@faf.one
Intended usage: COMMON · Restrictions: None
Author: James Wolfe · Change controller: FAF Foundation
Additive minor versions + optional in-document fields do not require re-filing
(media type + YAML structure unchanged; version field handles evolution).
17. Implementations#
Anyone may implement the format. Known implementations are listed in IMPLEMENTATIONS.md.
18. Change History#
| Version | Date | Changes |
|---|---|---|
| 0.1–0.6 | 2026-04-30 to 2026-05-01 | Drafts |
| 1.0 | 2026-05-01 | First stable version, for IANA registration |
| 1.1 | 2026-05-21 | Profiles (voice, knowledge); knowledge fact fields; parser requirements |
| 1.2 | 2026-11-02 | Forget rules and tombstones; say; unknown type / priority values valid; writers preserve unknown fields; readers accept higher minor versions; writers never lower version; date-times are strings; recalled memory is data; owner-only permissions; project.fafm. Additive |
End of Specification.