Skip to content

me-pack.md

Latest commit

 

History

History
123 lines (83 loc) · 4.74 KB

me-pack.md

File metadata and controls

123 lines (83 loc) · 4.74 KB

me pack

Manage memory packs.

Memory packs are YAML files containing pre-built collections of memories. They provide structured knowledge that can be installed into any engine -- things like framework documentation, best practices, or domain-specific reference material.

Commands

me pack validate

Validate a memory pack file.

me pack validate <file>
Argument Required Description
file yes Pack YAML file to validate.

Parses the YAML file and runs pack-specific constraint validation. Reports whether the pack is valid or lists the errors found.

me pack install

Install a memory pack into the active engine.

me pack install <file> [options]
Argument Required Description
file yes Pack YAML file to install.
Option Description
--dry-run Preview what would happen without making changes.
-y, --yes Skip confirmation for stale memory deletion.

The install process:

  1. Validates the pack file.
  2. Connects to the active engine.
  3. Finds existing memories from the same pack (by metadata).
  4. Deletes stale memories from previous versions (with confirmation).
  5. Creates all memories from the pack with pack.* tree prefixes and pack metadata.

Inserts use server-side ON CONFLICT DO NOTHING, so existing rows with the same id are left untouched. The command classifies and reports any skips:

  • Already present -- id is already tagged with this pack name and version. A benign no-op (e.g. re-running install on an unchanged pack).
  • Conflict -- id is held by something else (a different pack, a different version, or a non-pack memory). Surfaced as a warning and listed by id so a real collision isn't silently masked. Exit code remains 0.

Output

Text mode prints a multi-line summary:

✓ Installed pack 'foo' v2: 12 memories
    └ 5 stale removed (from previous version)
    └ 2 already present (skipped)

Pure re-installs of an unchanged version produce a single line:

✓ Pack 'foo' v2 already installed (15 memories present, no changes)

If any ids collide with non-pack memories, a warning follows the success line and lists the conflicting ids.

JSON mode (--format json) returns:

Field Description
pack Pack name.
version Pack version.
installed Memories actually inserted on this run.
staleRemoved Previous-version memories deleted before insert.
skipped Total memories skipped by ON CONFLICT DO NOTHING.
skippedIdempotent Skipped because already present at this version.
skippedConflict Skipped because the id is held by something not from this pack/version.
skippedConflictIds Array of conflicting ids (only present when skippedConflict > 0).
failed Memories in chunks that errored before reaching the server.
failedIds Array of ids in failed chunks (only present when failed > 0).
errors Per-chunk error detail: { chunkIndex, itemCount, ids, error } (only present when failed > 0).

Chunking and partial failures

Large packs are sliced into multiple batchCreate requests under the hood to fit under the server's request-body limit. Chunks are sent sequentially. If a chunk fails (network error, server error), siblings are not affected -- the successful chunks still land. The failed memories are reported under failed / failedIds / errors.

A partial install is crash-safe: re-running me pack install with the same pack file picks up where the previous run left off. The step-3 search finds the inserted memories as already-at-this-version (idempotent), and the missing ids are filled in. The text output adds a └ N failed (chunk error — re-run to retry) line and a clack.log.error block with per-chunk error detail when this happens.

Example

# Preview installation (predicts idempotent skips)
me pack install packs/typescript-best-practices.yaml --dry-run

# Install, auto-confirm stale deletion
me pack install packs/typescript-best-practices.yaml --yes

Dry-run output includes wouldSkipIdempotent (predicted from rows already at the target version) alongside wouldInstall and wouldDeleteStale. It does not predict conflicts with non-pack memories -- those only surface during the real install.

me pack list

List installed packs in the active engine.

me pack list

Searches for all memories with pack metadata and displays a table grouped by pack name, showing name, version, and memory count.