Agent memory blueprint

Agent Memory Blueprint

Treat agent memory as a bootable knowledge system, not as notes.

When to use this skill

Use this skill to:

• design a machine-first YAML memory blueprint for agents
• scaffold a new synthetic or private memory file
• validate structure and public-safety boundaries
• analyze an existing memory shape without printing detail contents
• prepare a public GitHub Skill package from a private architecture
• explain or maintain the four-layer memory model

When not to use this skill

Do not use this skill to:

• store or publish real private data
• publish real candidate, customer, resume, email, phone, profile URL, or recruiting data
• replace a database, CRM, ATS, RPA, crawler, scraper, or SaaS product
• bypass privacy review or treat --strict-public as a perfect leak detector

Operating model

Build four layers:

• Boot and routing: agent_boot, read_profiles, project_skill_cards, project_index
• Execution cards: compact project cards with current_state, next_action, paths, and do-not rules
• Detail sections: SOP, constraints, validation state, commands, and deeper project context
• History ledgers: append-only calendar_events_YYYY_MM sections for reports and retrospectives

Use multi-document YAML only when helpful. Top-level keys must be unique within and across documents.

Workflow

1. Analyze shape first

Run:

python scripts/analyze_memory_shape.py /path/to/memory.yaml --json

Use the report for structural facts only: top-level keys, read profiles, project cards, detail links, calendar sections, duplicate top-level keys, and public-risk marker counts. Do not copy live project content into public templates.

2. Choose a reference

• Use references/architecture.md for the four-layer model.
• Use references/schema.md and schemas/memory.schema.json for field contracts.
• Use references/update-protocol.md when editing a live private memory file.
• Use references/publication.md before preparing public GitHub content.

3. Scaffold

Run:

python scripts/scaffold_memory.py --output /path/to/memory.yaml --owner OWNER_NAME

The scaffold is synthetic. Replace it with real project cards only in private files outside the public repository.

4. Validate

Run:

python scripts/validate_memory.py /path/to/memory.yaml

Before publishing:

python scripts/validate_memory.py /path/to/memory.yaml --strict-public
python scripts/release_check.py

Strict-public fails likely emails, phone-like content, recruiting/profile URLs, secret-like assignments, and non-placeholder local paths such as C:\Users\real-user\..., D:\Projects\..., /Users/real-user/..., /home/real-user/..., /mnt/data/..., /workspace/..., /var/secrets/..., /opt/internal/..., or ~/private/....

Allowed placeholder path patterns include /path/to/..., /example/..., obvious values containing OWNER_NAME, PROJECT_ID, example, demo, or placeholder, and /tmp/... for tooling convenience.

5. Package

Run:

python scripts/package_skill.py --output dist/agent-memory-blueprint.zip

The package check must reject caches, .git, .env, private memory files, private/, backups/, .pyc, and nested dist/ output.

Design rules

• Keep one canonical private memory file per actual user/workspace.
• Let read_profiles choose execution, history, or update-memory mode.
• Keep project_skill_cards short enough for every execution.
• Put deep context in named detail sections.
• Keep calendar history outside default execution reads.
• Use supersedes or deprecation notes for correction instead of silent deletion.
• Every meaningful update should leave a concise human-readable event.
• Validation status must be truthful: passed, partial, blocked, or not_run.

Before publishing

• Run every YAML intended for publication through --strict-public.
• Run python scripts/release_check.py or make release-check.
• Inspect examples manually and confirm they are synthetic.
• Inspect dist/agent-memory-blueprint.zip.
• Do not publish live private memories, backups, real project logs, credentials, profile links, resumes, or personal data.
• Do not weaken strict-public to make unsafe content pass.

Resources

• assets/memory-template.yaml: public starter template
• examples/: synthetic public examples for productivity, software, and research workflows
• schemas/memory.schema.json: baseline JSON Schema for core structure
• scripts/analyze_memory_shape.py: private-safe structural analyzer
• scripts/package_skill.py: public-safe zip packager
• scripts/release_check.py: one-command release verification
• scripts/scaffold_memory.py: deterministic template generator
• scripts/validate_memory.py: structural and strict-public validator
• tests/: regression tests for validators, examples, and private-safe analysis
• references/architecture.md: architecture model
• references/schema.md: field contracts and naming rules
• references/update-protocol.md: live-memory editing procedure
• references/publication.md: GitHub/public-release boundary