memory-import

Memory Import

Bulk-import external material into workspace memory through a session — the unit of quota, audit, and gate evaluation. Three layers, two of which are yours:

Layer 1 — land the documents (zero LLM, do this first)

cloud memory imports open --workspace <ws>          # → { id }
cloud memory imports write-documents <id> --workspace <ws> --documents '[{"name":"…","content":"…"}]'

Raw documents become searchable in seconds. No quality bar here — that is Layer 2's job.

Layer 2 — distill (YOUR LLM, your compute)

Read the landed documents, then author candidate pages and submit them:

• One page per coherent topic, attached under the right hub (<hub>/<topic>.pkf, relative to the Memory root; do not prepend another memory/).
• Every candidate MUST carry the memory frontmatter block — the pipeline rejects the whole batch otherwise: {"type":"note","title":"…","description":"…","memory":{"memoryRole":"knowledge|procedure|action_result","source":"<where this came from, in words a human can read>"}}.
• Distill, don't dump: conclusions and procedures, not transcripts. The raw documents stay in Layer 1 as the reference layer.

cloud memory imports write-batch <id> --workspace <ws> --candidates '[{"pagePath":"…","contentDiff":"<full PKF body>"}]'

Layer 3 — commit (cloud-side gate, zero negotiation)

cloud memory imports commit <id> --workspace <ws>   # runs the evolution gate
cloud memory imports status <id> --workspace <ws>   # per-candidate verdicts

The gate REJECTS batches that lose retrieval coverage (a candidate replacing a page must not delete its keywords) or lack metadata. A rejected commit is final for the session: read the verdict, fix the candidates, open a NEW session, resubmit. Never re-submit an identical rejected batch — the Ledger rejects same-shape candidates for 30 days.

Routing: raw archive / small batch → L1 + owner review. Knowledge-base migration / high-quality distillation → L1 → L2 → L3 (semantic work on YOUR compute; the cloud only gates and records).