memory-blueprints

name	memory-blueprints
description	Apply or export declarative Blueprint directories — YAML/JSON packs of schemas, agent definitions, skills, and JSONL seed files — using `memory blueprints`. Use when working with a blueprint repo or exporting a project's graph as seed files.
metadata	{"author":"emergent","version":"1.1"}

Manage Emergent Blueprints using memory blueprints. A blueprint is a directory of YAML/JSON files and JSONL seed data that declaratively describes a project's schemas, agent definitions, skills, and initial graph objects/relationships.

New to Emergent? Load the memory-onboard skill first — it walks through designing and installing a schema from scratch.

Rules

• Project context is auto-discovered — the CLI walks up the directory tree to find .env.local containing MEMORY_PROJECT or MEMORY_PROJECT_ID. If .env.local is present anywhere above the current directory, --project is not needed. Only pass --project <id> explicitly when overriding or when no .env.local exists.

Concepts

• Blueprint — a directory containing schemas/ (or packs/ for backward compatibility), agents/, skills/, and/or seed/ subdirectories. Installed with memory blueprints install <source>.
• Seed data — pre-defined graph objects and relationships in per-type JSONL files under seed/objects/ and seed/relationships/. Applied after packs and agents.
• Key — a stable string identity on a seed object. Objects with a key are idempotent: skipped on re-apply (or upserted with --upgrade). Keyless objects are always inserted.
• Validate — memory blueprints validate <source> checks a blueprint for structural errors and cross-reference problems without making any API calls.
• Dump — memory blueprints dump <output-dir> exports a live project's graph as re-applyable seed files.

---

Commands

Install a blueprint

memory blueprints install <source>
memory blueprints install <source> --project <project-id>
memory blueprints install <source> --upgrade
memory blueprints install <source> --dry-run

<source> can be:

• A local directory path: ./my-blueprint
• A GitHub repo URL: https://github.com/org/repo
• A GitHub repo at a specific ref: https://github.com/org/repo#v1.2.0

For private GitHub repos, supply a token:

memory blueprints install <source> --token ghp_...
# or set MEMORY_GITHUB_TOKEN in the environment

Validate a blueprint (no API calls required)

memory blueprints validate <source>
memory blueprints validate https://github.com/org/repo
memory blueprints validate https://github.com/org/repo#v1.2.0

Validates the blueprint directory (or GitHub repo) offline — no project, no auth needed. Reports errors and warnings for:

• Packs — missing required fields, invalid relationship sourceType/targetType cross-references, duplicate names
• Agents — invalid flowType, visibility, or dispatchMode values; missing model.name
• Skills — missing name/description, empty content body
• Seed objects — missing type, keyless objects (warning)
• Seed relationships — missing endpoints, unresolvable srcKey/dstKey against seed objects

Exits 0 when clean or warnings-only, 1 when any error is found. Always validate before installing.

Export a project as seed files (dump)

memory blueprints dump <output-dir>
memory blueprints dump <output-dir> --project <project-id>
memory blueprints dump <output-dir> --types Person,Company,works_at

Exports all graph objects and relationships as per-type JSONL seed files into <output-dir>/seed/objects/ and <output-dir>/seed/relationships/. Files exceeding 50 MB are automatically split (<Type>.001.jsonl, <Type>.002.jsonl, …).

---

Blueprint directory layout

my-blueprint/
  schemas/                        # preferred (packs/ also supported for backward compat)
    <pack-name>.yaml          # one file per schema (.yaml/.yml/.json)
  agents/
    <agent-name>.yaml         # one file per agent definition (.yaml/.yml/.json)
  seed/
    objects/
      <TypeName>.jsonl        # one JSON object per line
      <TypeName>.001.jsonl    # split file (auto-generated by dump, or hand-authored)
    relationships/
      <TypeName>.jsonl        # one JSON object per line

All subdirectories are optional. Missing seed/ is not an error.

---

Seed file formats

Object record (seed/objects/<TypeName>.jsonl)

One JSON object per line:

{
  "type": "Person",        // required
  "key": "alice-smith",    // optional — stable identity; enables idempotent re-apply
  "status": "active",      // optional
  "labels": ["vip"],       // optional
  "properties": {          // optional
    "name": "Alice Smith",
    "role": "Engineer"
  }
}

Relationship record (seed/relationships/<TypeName>.jsonl)

Prefer key-based references when both objects have keys:

{ "type": "works_at", "srcKey": "alice-smith", "dstKey": "acme-corp" }

Fall back to entity IDs for keyless objects:

{ "type": "works_at", "srcId": "eid-abc123", "dstId": "eid-def456" }

Optional fields: weight (float), properties (object).

---

Flags reference

memory blueprints install <source>

Flag	Description
--project <id>	Target project ID or name
--upgrade	Update existing resources instead of skipping them
--dry-run	Preview only — no API calls
--token <tok>	GitHub PAT for private repos (also: MEMORY_GITHUB_TOKEN)

memory blueprints validate <source>

Flag	Description
--token <tok>	GitHub PAT for private repos (also: MEMORY_GITHUB_TOKEN)

No --project required — validation is fully offline.

memory blueprints dump <output-dir>

Flag	Description
--project <id>	Source project ID or name
--types <list>	Comma-separated type filter (default: all types)

---

Matching and idempotency

Resource	Matched by	Without --upgrade	With --upgrade
Pack	name field	skip if exists	update in place
Agent	name field	skip if exists	update in place
Seed object (keyed)	key field	skip if exists	upsert
Seed object (keyless)	—	always create	always create
Relationship	server deduplication	idempotent	idempotent

---

Workflow: apply seed data to a project

1. Ensure the project has the required schemas installed (types must exist before seeding).
2. Validate the blueprint offline first:

   memory blueprints validate ./my-blueprint
   

3. Run dry-run to preview actions:

   memory blueprints install ./my-blueprint --dry-run
   

4. Apply:

   memory blueprints install ./my-blueprint
   

5. Re-apply is safe — keyed objects are skipped (or upserted with --upgrade).

Workflow: clone a project's graph to another project

# Export from source project
memory blueprints dump ./exported --project <source-project-id>

# Validate the exported files
memory blueprints validate ./exported

# Apply to destination project
memory blueprints install ./exported --project <dest-project-id>

---

Notes

• Always set a key on seed objects you intend to re-apply — keyless objects are inserted anew on every apply, creating duplicates.
• Use srcKey/dstKey in relationship files whenever possible; srcId/dstId references break when re-applying to a different project.
• The dump command prefers key-based references automatically.
• memory blueprints validate exits 0 when clean or warnings-only, 1 when any error is found.
• memory blueprints install exits non-zero if any resource produced an error during apply.
• memory blueprints dump does not export packs or agent definitions — only graph objects and relationships.