Import existing memory and knowledge

Singularity can start with your existing memory, knowledge, and profile facts instead of synthetic starter rows. The destination is the canonical BeingMind in the being's owner-only state.json; no second memory store is created.

Choose a surface

• New being CLI: add --import-file /path/to/mind.json to the fully configured singularity run or singularity once command. The document is validated before state creation and persisted before the first model call.
• Existing-being first use: run singularity onboarding --import-file /path/to/mind.json --state-dir /path/to/state. The walkthrough starts only after the import report is accepted.
• Reusable CLI: run singularity import --file /path/to/mind.json --state-dir /path/to/state at any later time.
• Singularity Desktop first use: select the being's state directory, keep singularity run active, and choose Import existing mind….
• Singularity Desktop later: choose Import in the window actions. The result appears on Mind, and each imported memory shows its source.

Desktop reads the selected regular JSON file, forwards its raw bytes over the state directory's owner-only state-import.sock, and displays the runtime's report. It does not parse or write the mind itself. If the runtime is stopped, use the reusable CLI command; if the socket is unavailable, Desktop refuses with that instruction rather than creating a competing store.

File contract

The only accepted schema is singularity-mind-import-v1:

{
  "schema_version": "singularity-mind-import-v1",
  "source": { "kind": "<export type>", "id": "<stable source id>" },
  "memories": [{ "id": "<stable item id>", "text": "<existing memory>" }],
  "knowledge": [{ "id": "<stable item id>", "text": "<existing knowledge>" }],
  "profile": [{ "id": "<stable item id>", "text": "<existing profile fact>" }]
}

Use identifiers from the source export, not array positions that change on the next export. The arrays are optional, but at least one real record is required. Item IDs must be unique across the three arrays. Unknown keys and unsupported fields are errors; Singularity never silently drops them.

Validation and duplicates

The runtime parses and validates the entire document before changing state. It refuses non-regular files and symbolic links, files over 16 MiB, more than 1,000 items, a result that would exceed the 1,000-memory state bound, malformed JSON, an incorrect schema version, empty or control-character source fields, duplicate item IDs, empty or NUL-containing text, and oversized fields.

The pair of source identity and item ID is the repeat-import key:

| Incoming record | Result | |---|---| | New item and new text | imported | | Same source item, category, and text | unchanged | | Same text already retained from another source | attributed; no duplicate memory | | Same source item with changed category or text | conflicting; entire import refused |

An accepted document saves state atomically and appends one mind_imported event. A refused document leaves the original state unchanged. Both CLI and Desktop return imported, attributed, unchanged, conflicting, and rejected counts; item conflicts include category, item ID, and reason.

What remains unchanged

Imported profile records are profile-kind memories. They do not overwrite AgentIdentity. The operation cannot change the system prompt, self-imposed rules, learnings, current model, balance, cost or revenue accounting, finance policy, credentials, capabilities, or tool catalogue. It never runs a cycle or activates a financial action.