Skip to main content

.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#

TermDefinition
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).
ProfileThe memory shape/use-case discriminator (voice default, knowledge). See §3.
EtchWrite operation that stores memory
RecallRead operation that retrieves relevant memory
SessionOne 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).

ProfileUse-caseFacts shape
voice (default)Voice agents (VML)simple — string or {text, tags?}
knowledgeKnowledge/agent memoryrich 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, optional tag) held before promotion.
  • Smart Merge — at session end, an LLM-mediated decision per scratchpad entry: promote (→ soul) · keep_ephemeral (discard) · merge_into (combine). Decisions carry rationale + 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 a type).
  • 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.sessions stays reserved.
  • Facts tagged paralinguistic are 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_at is an RFC 3339 date-time string in UTC, written with an uppercase Z.
  • txt_hash keys a fact that has no id: the lowercase-hex SHA-256 of the UTF-8 bytes of the fact’s text, 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’s str.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 id or txt_hash. If both are present, id takes precedence. A txt_hash tombstone matches only facts without an id.

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#

OperationDescription
etch memoryStore fact(s) into a soul
recallRetrieve relevant memory for a session
scratchpadHold in-session ephemeral entries (voice, §7)
smart-mergePromote, keep or merge at session end (voice, §7)
forgetDelete 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.tombstones survive 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-canonical type / priority values; see §14.)
  • A writer MUST preserve an unknown type or priority value unchanged, except the §6.1 legacy mapping.
  • A writer MUST NOT write a lower version than 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 with Z. A timestamp with no offset is not RFC 3339: writers MUST include one (Z preferred).
  • version MUST be a quoted string (YAML reads an unquoted 1.2 as a number and 1.10 as 1.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 .fafm files MUST be written with owner-only permissions (0600 or 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).
  • .fafm files 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 version field. 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 / priority values. 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’s say (§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.fafm is project (shared) memory. It sits beside project.faf and SHOULD be version-controlled with the project.
  • Personal memory: its location is the holder’s choice: conventionally soul.fafm, a *.fafm.local file (still application/vnd.fafm+yaml content), 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 .fafm documents 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#

VersionDateChanges
0.1–0.62026-04-30 to 2026-05-01Drafts
1.02026-05-01First stable version, for IANA registration
1.12026-05-21Profiles (voice, knowledge); knowledge fact fields; parser requirements
1.22026-11-02Forget 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.