Memory Space Schema

This document defines the schema for schema.json files that configure memory spaces.

Root Object

Key	Type	Required	Description
name	string	Yes	Human-readable name for the space (e.g., "My Blog", "2024 Taxes")
slug	string	Yes	URL-safe identifier, used for directory name (e.g., "my-blog", "taxes-2024")
purpose	string	Yes	One sentence explaining what this space remembers and why
created	string	No	ISO date when space was created (YYYY-MM-DD)
locations	Location[]	Yes	Array of file/collection definitions
relationships	object	No	Map of "source → target" strings describing knowledge flow
maintenance	Maintenance	No	How and when to maintain this space
capture_hints	CaptureHint[]	No	Triggers for proactive data capture from conversation
suggested_tasks	SuggestedTask[]	No	AI-assisted tasks that can be performed in this space

Location Object

Each location defines either a single file or a collection of files.

Key	Type	Required	Description
path	string	Yes	File path relative to space root. Use [slug] or [date] for globs
type	"file" | "glob"	Yes	file = single file created immediately. glob = pattern for multiple files
purpose	string	Yes	What knowledge this location holds and when to use it
format	string	No	File format, typically "markdown"
sections	string[]	No	For files: suggested markdown sections (e.g., "## Overview")
frontmatter	object	No	For globs: expected YAML frontmatter fields and their types
lifecycle	Lifecycle	No	When to create, update, and archive entries
boundaries	Boundaries	No	What belongs here vs elsewhere
upgrade	Upgrade	No	When this location should be restructured
population	Population	No	For globs: how to name and create new entries

Path Patterns

• Static paths: overview.md, decisions.md, style-guide.md
• Single variable: drafts/[slug].md, sessions/[date].md
• Multiple variables: published/[year]/[slug].md, decisions/[date]-[slug].md

Variable types:

• [slug] — kebab-case identifier derived from title or name
• [date] — ISO date format YYYY-MM-DD
• [year] — Four-digit year YYYY
• [category] — User-defined category name

Lifecycle Object

Key	Type	Required	Description
create	string	Yes	When/why to create this file or first entry
update	string	Yes	When/why to modify existing content
archive	string | null	No	When to archive or delete. Null if content is permanent

Boundaries Object

Key	Type	Required	Description
include	string	Yes	What belongs in this location
exclude	string	Yes	What should go elsewhere

Upgrade Object

Key	Type	Required	Description
trigger	string	Yes	Condition that triggers restructuring (e.g., "When exceeds 50 entries")
migration	string	Yes	How to restructure (e.g., "Split into [category]/ subdirectories")

Population Object

For glob patterns, describes how to create new entries.

Key	Type	Required	Description
slug_format	string	No	How to generate slugs (e.g., "kebab-case-from-title")
date_format	string	No	Date format for [date] variables (typically "YYYY-MM-DD")
year_format	string	No	Year format for [year] variables (typically "YYYY")
example	string	No	Example path showing the pattern in use

Maintenance Object

Key	Type	Required	Description
frequency	string	Yes	How often to review (e.g., "Weekly", "Monthly", "After each session")
tasks	string[]	Yes	Specific maintenance actions to perform

CaptureHint Object

Defines conversational triggers that should prompt the AI to offer saving data to this space.

Key	Type	Required	Description
trigger	string	Yes	What to listen for in conversation (e.g., "User mentions a therapy session")
target	string	Yes	Which location this data should go to (e.g., "sessions/[date].md")
fields	string[]	Yes	Key data points to capture (e.g., ["topics", "mood", "homework"])
prompt	string	Yes	Natural language offer to the user (e.g., "Want me to capture notes from that session?")

Example:

{
  "trigger": "User mentions completing a therapy session",
  "target": "sessions/[date].md",
  "fields": ["date", "topics discussed", "mood before/after", "homework assigned"],
  "prompt": "Want me to capture notes from that session?"
}

SuggestedTask Object

Defines recurring tasks the AI can proactively offer to help with.

Key	Type	Required	Description
name	string	Yes	Short task name (e.g., "Session Prep")
description	string	Yes	What the task does (e.g., "Review recent sessions before your next appointment")
trigger	string	Yes	When to offer this task (e.g., "Before scheduled therapy", "Weekly", "On request")

Example:

{
  "name": "Progress Review",
  "description": "Summarize patterns and growth across sessions over a time period",
  "trigger": "Monthly, quarterly, or when feeling stuck"
}

Relationships Object

Free-form object mapping source locations to targets with descriptions.

{
  "source → target": "How knowledge flows from source to target",
  "sessions/ → insights/": "Insights emerge from session themes",
  "decisions.md ↔ stakeholders/": "Decisions involve stakeholders (bidirectional)"
}

Arrow conventions:

• → one-way flow
• ↔ bidirectional relationship

Frontmatter Types

When defining frontmatter schemas, use these type notations:

Notation	Meaning
string	Any text value
date	ISO date (YYYY-MM-DD)
number	Numeric value
boolean	true/false
string[]	Array of strings
"a"|"b"|"c"	Enum of specific values
type|null	Optional field (can be null)

Design Principles

1. Memory spaces store knowledge, not files — Raw files (PDFs, receipts) go in assets/. The space holds synthesized knowledge.

2. Every space needs overview.md — First location should always be an overview file with the space's purpose, current status, and key facts.

3. Prefer files over globs initially — Start with single files. Add globs when volume demands (>20 similar entries).

4. Make upgrade paths explicit — Include upgrade for any location that might outgrow its structure.

5. Boundaries prevent sprawl — Every location needs clear include/exclude rules.

6. Maintenance is mandatory — If you can't describe how to maintain it, the schema is incomplete.

7. Relationships show knowledge flow — Document how locations inform each other.

8. Capture hints make spaces proactive — Define 2-3 conversation triggers so the AI knows when to offer saving data to this space.

9. Suggested tasks make spaces actionable — Define 2-3 recurring tasks so the AI can proactively offer helpful actions.