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)
bashcloud 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 anothermemory/). - Every candidate MUST carry the
memoryfrontmatter 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.
bashcloud memory imports write-batch <id> --workspace <ws> --candidates '[{"pagePath":"…","contentDiff":"<full PKF body>"}]'
Layer 3 — commit (cloud-side gate, zero negotiation)
bashcloud 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).


