memory promote

What It Does

memory promote takes promotion candidates and writes durable docs under docs/memory/**, such as decisions, glossary entries, or plans. It does not ingest those new worktree files. Review and commit them before a later ingest makes them searchable.

When To Use / When Not To Use

When to use it

A decision, glossary term, or plan should become durable project memory.
You want future retrieval to find the result without reopening session history.

When not to use it

The note is still provisional. Keep it in working memory with memory wrap.
You only want to resume active work. Use memory recall.

Syntax

pnpm ragit memory promote --input <path|-> \
  [--dry-run] [--format text|json|both] [--cwd <path>]

Arguments And Options

--input <path|->: Required JSON payload describing promotion candidates.
--dry-run: Validate candidates and planned target docs without writing.
--format text|json|both: Choose text, JSON, or both.
--cwd <path>: Run against another repository.

Input And Output Contract

{
  "promotionCandidates": [
    {
      "type": "adr",
      "title": "Keep refresh handling outside manifest mutation",
      "summary": "Separates active auth refresh logic from snapshot writes.",
      "rationale": "Preserves snapshot contract stability.",
      "nextReviewAt": "2026-06-01"
    }
  ]
}

JSON output includes createdFiles, plannedFiles, sourceHeadSha, ingested, dryRun, and warnings.
--dry-run tells you which document files would be created.
Promotion reports ingested: false. A successful apply warns you to commit the generated documents and run ragit ingest --all for the first snapshot or a supported incremental ingest after a trusted base exists.

Examples

Human terminal flow:

pnpm ragit memory promote --input promotion-batch.json
git add docs/memory
git commit -m "promote durable memory"
pnpm ragit ingest --all

Agent-oriented flow:

pnpm ragit memory promote --input promotion-batch.json --dry-run --format json

Failures And Cautions

Promotion is the deliberate filter that keeps docs/memory/** clean. Do not use it for raw scratch notes.
The payload must use valid promotion candidate types and fields.
Promoted docs affect searchable retrieval only after review, commit, and ingest. Do not index their uncommitted worktree contents under the previous HEAD.

memory promote

On this page