memory-blueprints

name	memory-blueprints
description	Apply and export Emergent Blueprints — declarative directories of template packs, agent definitions, and seed data applied with `memory blueprints`. Use when setting up a project from a blueprint, seeding graph data, or exporting an existing project's graph as re-applyable seed files.
metadata	{"author":"emergent","version":"1.0"}

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 template packs, agent definitions, and initial graph objects/relationships.

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

Rules

• Never run memory browse — it launches a full interactive TUI that blocks on terminal input and will hang in an automated agent context.
• Always prefix memory commands with NO_PROMPT=1 (e.g. NO_PROMPT=1 memory <cmd>). Without it, the CLI may show interactive pickers when no project, agent, MCP server, skill, or agent-definition ID is provided. Do not add this to .env.local — it must only apply to agent-driven invocations.
• Always supply a project with --project <id> on project-scoped commands, or ensure MEMORY_PROJECT is set.

Concepts

• Blueprint — a directory containing packs/, agents/, and/or seed/ subdirectories. Applied with memory blueprints <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.
• Dump — the memory blueprints dump <output-dir> subcommand exports a live project's graph as re-applyable seed files.

---

Commands

Apply a blueprint

memory blueprints <source>
memory blueprints <source> --project <project-id>
memory blueprints <source> --upgrade
memory blueprints <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 <source> --token ghp_...
# or set MEMORY_GITHUB_TOKEN in the environment

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/
  packs/
    <pack-name>.yaml          # one file per template pack (.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 <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 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 template packs installed (types must exist before seeding).
2. Run dry-run to validate seed files and preview actions:

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

3. Apply:

   memory blueprints ./my-blueprint
   

4. 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>

# Apply to destination project
memory blueprints ./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.
• Exit code is 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.