Use frontmatter to enforce validation and set conditional (read-only / team-scoped) permissions

[groksrc]

Motivation

Basic Memory already treats frontmatter as a first-class control surface: type drives schema resolution, and any custom key is captured as entity_metadata and indexed. The schema system (Picoschema validation, inference, drift) reads from there too. Two capabilities are a natural extension of that surface and are worth landing — or at least designing the frontmatter contract for — in the v1.0 window, since both touch the write path:

1. Tighter validation — make schema validation enforce-able from frontmatter, not just advisory.
2. Conditional permissions — let frontmatter mark a note (or type) as read-only / locked so agents can't silently edit or delete it.

Both are "the file is the source of truth" features: the rule travels with the note, survives moves, and works in git without a side database.

Part 1 — Frontmatter-driven validation

Today validation is advisory (schema_validate reports warnings/errors but writes still go through). Proposal:

• A note's schema (inline schema: dict, a schema: reference, or the implicit type schema) can declare required fields and enforcement level.
• On write_note / edit_note, the write path consults that schema. At minimum surface violations back to the agent in the tool result; optionally reject writes that violate a schema marked enforce: true.
• Keep the default non-breaking (warn, don't block) so existing notes/imports don't start failing; enforcement is opt-in per type/note.

This turns the existing ValidationReport machinery into something that can guard the write path instead of only being run on demand.

Part 2 — Conditional permissions (write/edit protection)

Let frontmatter declare that a note is protected, e.g.:

---
title: Release Process
type: runbook
locked: true          # or: permissions: read-only
---

When a note is locked / read-only, edit_note and delete_note (and overwriting write_note) refuse the operation and return a clear, actionable message ("this note is marked read-only in frontmatter; remove locked: true to edit"). This is the single most useful case: stable runbooks, canonical references, and decision records that an agent should not casually rewrite.

Open questions to settle in design:

• Note-level vs type-level (schema) declaration — likely support both, note-level wins.
• Whether the lock can be lifted by an agent editing the frontmatter itself (escape hatch vs. genuine guard) — probably a config/flag decision.
• Interaction with imports and move_note (move should still be allowed; content edit should not).

Part 3 — Teams extension (forward-looking, may be a separate issue)

For Basic Memory Teams, the same frontmatter permission surface generalizes from a binary lock to scoped read / write / edit grants applied to agents, users, or groups:

---
permissions:
  read: [team:research, alice]
  write: [alice]
  edit: [alice]
---

This is out of scope for the single-user v1.0 core but the frontmatter contract designed in Parts 1–2 should not paint us into a corner — the permissions: key should be shaped so the team-scoped form is a superset of the local read-only form, not a redesign.

Non-goals (for the v1.0 core)

• Full ACL enforcement / identity model — that's the Teams extension.
• Encryption or hiding note content on disk — this is operation-gating at the MCP/CLI layer, the file stays plain markdown.
• Changing the default behavior for existing notes (validation stays advisory unless opted in; notes without a lock key behave exactly as today).

Why v1.0

Both parts establish a frontmatter contract (enforce, locked/permissions) that's hard to change later once notes in the wild use it. Settling the key names and the precedence rules during the breaking-change window — even if Teams enforcement ships afterward — is the cheap moment to do it.

🤖 Generated with Claude Code

[claude]

Claude finished @groksrc's task in 2m 20s —— View job

---

Issue Triage

• Read issue and understand request
• Classify issue type and priority
• Search for duplicate issues (none found)
• Apply labels (see note below)
• Provide triage summary

---

Triage Analysis

Type: Feature request — new frontmatter-contract capabilities that extend existing schema/validation infrastructure. No duplicate issues found.

Priority: Medium — non-breaking by design (opt-in enforcement, no behavior change for existing notes), but design-critical for v1.0 since the frontmatter key names (enforce, locked, permissions) need to be locked in during the breaking-change window before notes in the wild use them.

Components Affected:

• MCP tools — write_note, edit_note, delete_note (write-path gating)
• Schema/validation — src/basic_memory/schema/validator.py (ValidationResult, validate_note) and src/basic_memory/schemas/schema.py (ValidationReport)
• Markdown parsing — src/basic_memory/markdown/entity_parser.py (frontmatter extraction, entity_metadata)
• API — src/basic_memory/api/v2/routers/knowledge_router.py and schema_router.py

Complexity: Complex — touches the write path across MCP tools and API layer, requires design decisions about escape-hatch semantics (can an agent unlock itself?), and needs to be shaped so the Teams ACL extension is a superset rather than a redesign.

---

Code Context

The current state of the codebase:

• Validation is soft-only: validate_note() in schema/validator.py returns warnings/errors but nothing blocks writes — this would need a new enforcement mode behind enforce: true in frontmatter
• No locked/permissions handling exists: write_note.py, edit_note.py, and delete_note have no frontmatter-gating logic; entity_parser.py normalizes all frontmatter into entity_metadata as strings but makes no access-control decisions
• Schema frontmatter fields already validated: schema/validator.py lines 118–143 validate settings.frontmatter fields, so the plumbing for reading frontmatter during validation already exists
• Overwrite guard exists: write_note.py has an effective_overwrite flag that could be the anchor point for locked: gating

---

Design Questions to Settle (noted from issue)

1. Key names: locked: true vs permissions: read-only — the issue correctly identifies these need to be settled now so the Teams superset (permissions: read/write/edit with scoped grants) is forward-compatible
2. Escape hatch: Should an agent be able to edit frontmatter to remove locked: true? Needs a config/flag decision — probably a project-level config option
3. move_note behavior: Issue proposes moves should still be allowed when locked: true; this needs explicit handling
4. Enforcement level: Part 1's enforce: true should default to warn-only; only block when explicitly set

---

Suggested Implementation Sequence

1. Design the frontmatter contract (key names, precedence, Teams superset shape) — low code cost, high value
2. Part 2 first (locked/read-only) — simpler, higher immediate value for users, single write-path check
3. Part 1 second (enforce validation on write) — hooks into existing ValidationReport machinery
4. Part 3 later (Teams scoped permissions) — separate issue, builds on the contract established here

---

Note on labels: The priority/complexity/component labels referenced in the triage template (medium, complex, mcp-tool, etc.) don't exist in the repository. The issue already has enhancement and v1.0 which are the most relevant existing labels.

[hegu-1]

This is exactly the frontmatter contract I’d want in a personal memory vault.

For local-first / markdown-first memory, the important part is that protection travels with the note instead of living only in an external permission database. A note that says “I am canonical” or “I am read-only” should remain protected after a move, git sync, tool change, or agent handoff.

I’d separate a few cases explicitly:

permissions:
  read: [agent:any]
  append: [agent:any]
  edit: [user:owner]
  delete: [user:owner]
lock_reason: canonical-decision-record

That keeps append different from edit. For personal vault usage, append-only is often the useful middle state: agents can add observations or links, but cannot rewrite the authored memory itself.

A minimal local contract could be:

• locked: true = no content edits or deletes through MCP/CLI
• append_only: true = agents may append a dated section, not rewrite existing prose
• managed_blocks = agents may update only explicitly fenced regions
• enforce: true = schema violations block writes, not just warn
• unlock_requires: user = agent cannot grant itself permission by editing frontmatter

The escape-hatch question feels load-bearing. If an agent can remove locked: true through the same write path it is trying to use, the lock is mostly advisory. I’d make “remove or weaken a lock” a different capability from normal note editing.

I’ve been exploring this from a Personal AI OS / Memory Vault angle: the source-of-truth should be user-owned markdown, while agents operate through explicit write modes and provenance rather than silently mutating memory.

Related public projects:

• https://github.com/hegu-1/personal-memory-vault-starter
• https://github.com/hegu-1/personal-ai-os