Memzoi OKF Profile

Memzoi uses an OKF v0.1 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.

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/<project-key>/
    memory.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/MCP proposal inbox is still DB-local workflow state until a later lifecycle slice wires file proposals into commands.
• ~/.memzoi/projects/<project-key>/memory.db is derived runtime state for canonical records, plus current CLI/MCP proposal state. memzoi rebuild refuses to discard readable open proposals; if the existing DB is corrupt or unreadable, rebuild treats it as derived-cache recovery and may discard DB-local proposal state.
• ~/.memzoi/projects/<project-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
version: okf/v0.1
profile: memzoi/v0
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
visibility: repo
confidence: confirmed
applies_to:
  - apps/active/**
source: human
source_ref: issue://123
supersedes: old-data-client
expires: 2027-01-01
---
# 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 extend OKF v0.1 for Memzoi:

Field	Meaning
lane	Memzoi memory lane. Valid values are session, semantic, episodic, and procedural. Records without lane are accepted as semantic for backward compatibility.
status	Lifecycle state. Canonical active record value is active; inbound current is accepted as an alias for active and should be normalized on write.
visibility	Sharing boundary. Valid values are public, private, repo, team, and org. Exports skip private records.
confidence	Numeric confidence 0.0-1.0 or a label. Label mappings: confirmed -> 1.0, likely -> 0.75, uncertain -> 0.4.
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.
supersedes	Optional record ID replaced by this record. Prefer this over mutating old records in place.
expires	Optional date or timestamp after which the record should stop participating in recall/precheck unless renewed.

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.

Record status values:

• active
• superseded
• expired
• tombstoned
• redacted

Importer compatibility:

• Accept current as an alias for active.
• Accept numeric confidence values and the labels confirmed, likely, and uncertain.
• Normalize generated canonical files to active rather than current.

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
version: okf/v0.1
profile: memzoi/v0
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
---
# 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
• type
• title
• description
• lane
• status
• proposal
• timestamp
• sensitivity

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 one or more existing memories. Requires supersedes.
tombstone	Propose marking an existing memory intentionally inactive or removed. Requires proposal.target.

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.
unknown	Conservative default requiring review.

Validation checks:

• status must be proposed.
• 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.
• supersede proposals must include at least one supersedes target.
• tombstone proposals must include proposal.target.
• 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

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.

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	Runtime memory.db via importer/rebuild
Refresh agent-facing projections	Runtime exports/* via export commands