memory promote

What It Does

memory promote takes promotion candidates and writes durable docs under docs/memory/**, such as decisions, glossary entries, or plans. When HEAD is available, it then ingests those docs so they become searchable immediately.

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, planned target docs, and planned ingest 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 doc files and ingest targets would be touched.
If HEAD does not exist, promotion still plans file creation but warns that ingest is skipped.

Examples

Human terminal flow:

pnpm ragit memory promote --input promotion-batch.json

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 after ingest, not before.

memory promote

On this page