Memzoi OKF Profile

Memzoi uses ordinary OKF Markdown with the unversioned memzoi profile for reviewable, file-native memory. The profile defines where records live, which frontmatter fields Memzoi understands, and which files are reserved for human navigation or logs. Per-file OKF version declarations are not part of the profile.

Before Memzoi 1.0, format changes are hard cutovers. Older artifacts are rejected and must be manually upgraded or removed; Memzoi does not provide legacy readers, inferred defaults, dual writes, or automatic migrations.

This page describes the target authored-memory shape. Runtime indexes are derived from these files and can be rebuilt.

Source tree

.memzoi/
  config.toml        # optional repo workflow policy
  index.md
  log.md
  proposals/
    pending/
      <proposal-id>.md
  records/
    <path-concept-id>.md

~/.memzoi/
  config.toml        # optional user-global workflow policy
  projects/<repository-key>/
    config.toml
    shared.db
    repo-lifecycle.lock
    worktrees/<worktree-key>/
      index.db
      exports/

Rules:

• .memzoi/records/*.md is the canonical home for applied durable records.
• .memzoi/proposals/pending/*.md is the review packet shape for proposed memory mutations before they become canonical records.
• .memzoi/config.toml can set repo workflow policy, such as [workflow] proposal_approval = "manual". It overrides the user-global ${MEMZOI_HOME:-~/.memzoi}/config.toml.
• Proposal files are schema-defined review packets. The current CLI proposal inbox is still DB-local workflow state until a later lifecycle slice wires file proposals into commands. MCP cannot create or change proposal state.
• ~/.memzoi/projects/<repository-key>/shared.db is the durable local authority for local/session memory and current CLI proposal state. Linked worktrees share it. Rebuild does not discard it and fails closed if it is unreadable.
• ~/.memzoi/projects/<repository-key>/worktrees/<worktree-key>/index.db is a disposable projection of that checkout's canonical records plus shared runtime mirrors. memzoi rebuild replaces this index while preserving shared.db, including open proposals.
• ~/.memzoi/projects/<repository-key>/worktrees/<worktree-key>/exports/ contains generated projections such as OKF exports and agent instruction files. Do not author canonical records there.

Path concept IDs

A path concept ID names the concept represented by an OKF file path. It is not required to be an exact repository file path; use applies_to for repository paths affected by a record.

For canonical records, the file path is:

.memzoi/records/<path-concept-id>.md

Path concept ID rules:

• Use lowercase ASCII letters, digits, hyphens, and / separators.
• Start and end each segment with a letter or digit.
• Do not use empty segments, ., .., leading /, or trailing /.
• Do not include the .md extension in the concept ID.
• Keep IDs stable after review; supersede a record instead of renaming to change meaning.
• Avoid reserved names index and log as terminal segments.

Examples:

.memzoi/records/project/package-manager.md
.memzoi/records/apps/active/data-fetching.md
.memzoi/records/security/no-secrets-in-memory.md

Reserved index.md and log.md

index.md is reserved for human navigation. An OKF index file must not have YAML frontmatter and must not define a memory record or proposal.

log.md is reserved for append-only human-readable notes or import/apply receipts. It must not define a memory record or proposal. If a machine-readable event log is needed, store it in derived runtime state or a dedicated future profile file, not as record frontmatter on log.md.

Record frontmatter

A canonical record is a Markdown file with YAML frontmatter followed by the human-readable memory body.

---
id: use-react-query-in-apps-active
kind: memory
profile: memzoi
type: decision
lane: semantic
title: Use React Query in apps/active
description: apps/active uses React Query for server state.
timestamp: 2026-07-05T00:00:00Z
status: active
scope: repo
visibility: repo
content_class: general_repo_knowledge
confidence: 1.0
applies_to:
  - apps/active/**
source: human
source_ref: issue://123
supersedes: old-data-client
retention:
  explicit_expires_at: 2027-01-01T00:00:00Z
origin:
  origin_key: issue:123:accepted-decision
  route: repository_materialization
---
# Use React Query in apps/active

apps/active uses React Query for server state and should not add a second data-fetching cache.

Memzoi extension fields

These fields define the current Memzoi profile:

Field	Meaning
lane	Required Memzoi memory lane. Valid values are session, semantic, episodic, and procedural.
status	Required lifecycle state. Canonical active record value is active; aliases such as current are rejected.
visibility	Sharing boundary. Valid values are public, private, repo, team, and org. Exports skip private records.
confidence	Required numeric confidence from 0.0 through 1.0. Label aliases are rejected.
applies_to	Repository paths, path prefixes, or trailing /** scopes where the record is relevant. This is separate from the path concept ID. General glob syntax is not part of the current matcher.
source	Short provenance kind such as human, agent, import, issue, pr, or doc.
source_ref	Optional durable reference for provenance, such as issue://123, pr://45, a commit SHA, or a URL.
proposal_id	Optional ID of the review packet that approved the record. This is proposal lineage, not evidence provenance, and is kept separate from source/source_ref.
supersedes	Optional record ID replaced by this record. Prefer this over mutating old records in place.
retention	Required current-format retention facts. Semantic/procedural records use an empty object unless explicitly expiring; episodic records require occurred_at; session records require started_at. Optional explicit_expires_at must be RFC 3339.
origin	Required content-free source-event identity containing repository-scoped origin_key and route. Exact source replay uses this identity independently of record expiry.
lineage	Optional renewal or session-successor relationship containing kind and predecessor_id. It is separate from supersedes.

source and source_ref are independently optional. Memzoi preserves missing evidence as null across canonical render, rebuild, recall, and export; it does not fabricate a concept ID or route name as evidence.

Memory lanes:

• session: active task context, handoff notes, checkpoints, or current working assumptions. Raw transcripts should remain local by default.
• semantic: durable project truths such as facts, decisions, constraints, preferences, warnings, and risks.
• episodic: chronological project memory such as session summaries, incident notes, migration notes, and handoff history.
• procedural: reusable workflows, runbooks, debugging recipes, release processes, and agent procedures.

lane is orthogonal to type: lane describes how the memory is used and retained, while type describes the knowledge record's content shape.

Retention is a temporal input to the complete current-assertion decision. Session records close at the earliest terminal boundary, inactivity lease, seven-day cap, or explicit expiry. Episodic records have a 30-day ordinary window, extendable by authorized facts to at most 90 days. Semantic and procedural records have no age TTL. At a retention boundary the record becomes query-only; its canonical body is not rewritten or deleted.

Record status values:

• active
• superseded
• expired
• tombstoned
• redacted

Current-profile readers require the exact serialized field names and values shown above. They do not infer omitted scope, classification, status, confidence, retention, or origin data.

Proposal frontmatter

A proposal file is an intended memory mutation that has not yet been applied. It is a verbose review packet, not durable memory itself.

Pending proposal files live under:

.memzoi/proposals/pending/<proposal-id>.md

The initial proposal status is always proposed. Do not confuse file proposal status with the operational CLI inbox states pending, validated, approved, applied, and rejected.

---
id: mem_2026_07_06_auth_001
kind: proposal
profile: memzoi
retention: {}
origin:
  origin_key: issue:123:proposal
  route: repository_proposal
type: decision
lane: semantic
title: Protected routes must validate sessions server-side
description: Protected API routes must validate sessions server-side instead of trusting client auth state.
status: proposed
proposal:
  action: create
  proposed_by: agent
  proposed_at: 2026-07-06T00:00:00Z
  reason: Learned during auth middleware migration.
  confidence: medium
scope:
  kind: project
  paths:
    - src/auth/**
tags:
  - auth
  - middleware
  - security
timestamp: 2026-07-06T00:00:00Z
created_by: agent
sources:
  - path: src/auth/session.ts
supersedes: []
sensitivity: repo-safe
content_class: general_repo_knowledge
---
# Protected routes must validate sessions server-side

Protected API routes must validate the session server-side. Do not trust client-side auth state for authorization decisions.

Required proposal fields:

• id
• kind
• profile
• type
• title
• description
• lane
• status
• proposal
• timestamp
• sensitivity
• content_class
• retention
• origin

The nested proposal object requires:

• action
• proposed_by
• proposed_at

Proposal actions:

Action	Meaning
create	Propose a new canonical memory record.
supersede	Propose a new memory that replaces exactly one active memory. Requires one supersedes target and proposal.reason.
tombstone	Propose marking exactly one active memory intentionally inactive. Requires proposal.target and proposal.reason.

update is intentionally unsupported in the first file profile. Meaningful changes should usually create a superseding memory rather than silently editing an existing record in place.

Proposal sensitivity values:

Sensitivity	Meaning
repo-safe	Safe to commit after review.
local-only	Useful locally but should not become repo-shared memory.
sensitive	Requires explicit human review before any sharing.
secret	Must not be committed or applied into repo records.
raw-transcript	Raw conversation content that must not become repo-shared memory.
private-personal-data	Private personal information that must not become repo-shared memory.
temporary-state	Short-lived task state that belongs in local/session memory rather than canonical repo memory.
unknown	Conservative default requiring review.

New packets should always declare sensitivity. Legacy packets that omit it remain readable as unknown, and every non-repo-safe value is blocked at canonical apply even if the packet or DB proposal was auto-approved.

Validation checks:

• Pending packets use status: proposed. Resolved packets use status: applied or status: rejected and include matching resolution metadata.
• proposal.action must be create, supersede, or tombstone.
• lane must be session, semantic, episodic, or procedural.
• type must use current lowercase Memzoi values such as decision, fact, procedure, risk, or failed_attempt.
• sensitivity must be one of the listed sensitivity values.
• create proposals cannot name a target.
• supersede proposals must include exactly one supersedes target and no proposal.target.
• tombstone proposals must include exactly one proposal.target and no supersedes entries.
• supersede and tombstone require a reviewable proposal.reason.
• Apply verifies that the target exists, is active, has the same scope kind and scope ID, and has not changed since proposal.proposed_at.
• The body must be non-empty and should include enough review context to understand the intended memory change.

Proposal-to-record mapping:

.memzoi/proposals/pending/mem_2026_07_06_auth_001.md
  -> approve/apply
.memzoi/records/semantic/decisions/auth-session-validation.md
.memzoi/proposals/resolved/applied/mem_2026_07_06_auth_001.md

Rejected packets move to resolved/rejected/ instead and create no canonical record. A repo-safe resolved packet retains the reviewed proposal evidence and adds a Git-readable outcome, reviewer, timestamp, reason, and affected record IDs. A non-repo-safe packet instead becomes a generic create-shaped receipt: its proposal ID, file ID, content, and review-only fields are replaced by deterministic hash-only identities and a content digest. Either original alias can still replay the stored rejection through a hashed lookup that does not echo the alias.

For an applied packet, canonical source/source_ref point to its original evidence locator (for example path plus src/auth/session.ts), while proposal_id points to the packet that approved the change. Rebuild and OKF exports preserve both. Recall citations deliberately cite the evidence fields; audit events and resolved packets carry the proposal lineage.

The resulting canonical record may be a compact projection of the proposal. Review-only fields such as proposal.reason, proposal confidence, and review notes do not need to be copied into canonical record frontmatter unless they remain durable project knowledge.

A supersede apply preserves the old record and its evidence with status: superseded, then creates an active replacement whose supersedes field points to the old record. A tombstone apply preserves the target's body, source, tags, paths, and earlier lineage while changing its status to tombstoned; the resolved packet retains the reason. Both changes and their derived search updates commit through the same all-or-nothing lifecycle as create.

Compactness policy:

proposal = review packet
record   = compact durable memory
index    = generated machine projection

Prefer one canonical record per durable concept, decision, workflow, warning, handoff, or reusable cluster. Avoid generating one file per tiny observation.

Generated exports

Runtime exports/ is generated output. It may contain OKF-shaped Markdown and agent instruction projections, but those files are not canonical authored memory.

Use this boundary when deciding where to edit:

Need	Edit
Add a proposed memory	DB-local proposal workflow (memzoi propose)
Apply an approved memory	.memzoi/records/*.md through the apply/importer flow
Rebuild search/context indexes	Per-worktree index.db via importer/rebuild
Refresh agent-facing projections	Per-worktree exports/* via export commands