# Core concepts

The data model behind the API: Spaces, Entries and versions, files, knowledge, memory, branches, and access control.

The source layer in Mirabase has one kind of data: an **Entry with immutable versions**. A file is how you locate an Entry, knowledge is what processing produces from it, and part of memory comes from it.

```text
Entry
├─ id, space_id, title, metadata
├─ latest_version_id      newest committed version
├─ current_version_id     version serving search
├─ file                   { path, size, media_type, etag } or null
├─ knowledge              { state, indexed_version_id }
├─ memory                 { scope, kind, pinned, exclude } or null
├─ memory_exclude         kept out of memory distillation
└─ access                 { role, capabilities }
```

## Space

A Space is the boundary for permissions and paths. Every account has a default Space, and [`POST /v2/spaces`](https://mirabase.io/developers/api/spaces.md#spaces-create) creates more. Members, roles, and the file tree are all per Space.

An account can hold many Spaces (up to `tenant_spaces`, see [Rate limits and quotas](https://mirabase.io/developers/conventions.md#rate-limits)), so you can give each end user or each project its own. Deleting a Space deletes everything in it and cannot be undone, and the default Space cannot be deleted: see [`DELETE /v2/spaces/{space_id}`](https://mirabase.io/developers/api/spaces.md#spaces-delete).

### One Space per end user

When end users must be kept strictly apart, give each one a Space: files, knowledge, and memory are all kept per Space, which metadata cannot do. Set your own user id as the Space's `external_id`, then write `ext:<external_id>`, such as `ext:user-42`, wherever a Space id goes: in a path, in `?space_id=`, and in `space_ids` in a request body. There is no mapping table to keep.

[`PUT /v2/spaces/ext:<external_id>`](https://mirabase.io/developers/api/spaces.md#spaces-ensure) returns the Space or creates it. Two requests that arrive together create one Space, and calling it again is safe, so one call before the first write for a new user is enough. In the SDKs this is `spaces.ensure`, and `spaceFor` (`space_for` in Python) also returns a client pinned to that Space.

curl:

```bash
# Returns the Space whose external_id is user-42 (200), or creates it (201).
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "User 42"}'

# ext:user-42 works wherever a Space id does.
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42/files?path=/notes/plan.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary "We ship on Friday."
```

TypeScript:

```ts
// A client pinned to the user's Space. The Space is created on the first call.
const user = await mirabase.spaceFor("user-42", { name: "User 42" });

await user.files.write("/notes/plan.md", "We ship on Friday.\n");
const hits = await user.search("when do we ship?"); // reads this Space only
```

Python:

```python
# A client pinned to the user's Space. The Space is created on the first call.
user = mb.space_for("user-42", name="User 42")

user.files.write("/notes/plan.md", "We ship on Friday.\n")
hits = user.search("when do we ship?")  # reads this Space only
```

- `search`, `context`, and `answer` without `space_ids` read every Space the key can read, not only the default Space. When a request is about one user, name that user's Space. In the SDKs, a client pinned to a Space reads that Space only.
- [`GET /v2/spaces?external_id=`](https://mirabase.io/developers/api/spaces.md#spaces-list) looks a Space up by `external_id`, returns at most one, and never creates one (`spaces.findByExternalId` and `spaces.find_by_external_id` in the SDKs).
- Deleting a Space frees its `external_id` for reuse.

## Entries and versions

An Entry is the stable identity of a source: a file, a URL, or a piece of text. Each change of content makes a version. Versions are immutable, and the service keeps the chain.

- `latest_version_id` is the newest committed version. Reads use it by default, so you can read what you just wrote.
- `current_version_id` is the version `search` and `context` read from. It equals `latest_version_id` once that version is indexed, and stays on the earlier version while a newer one is still processing. It is absent until the first version finishes processing.
- A new title is also a new version, because the title is indexed. The only thing you can change on a version is its `message`.

You can reach an Entry by path, by id, or by meaning through search. All these access methods share the same identity, permissions, and version chain.

## Files

An Entry with a path is a file. The path is the identity: the same bytes at two paths are two files. Renames and moves keep the Entry id. An Entry can also have no path, such as a URL or text added through `ingest`: its `file` is `null`.

**Use `files` when you have a path and `entries` when you have an id**. Both take the same read parameters. See [Files and versions](https://mirabase.io/developers/files.md).

## Knowledge

Knowledge is not a separate resource. It is the processing state of an Entry. After a write commits, the service parses, chunks, and indexes it, and `knowledge.state` reports progress:

| State | Meaning | What works |
| --- | --- | --- |
| `readable` | Committed | Read the original by path or id |
| `searchable` | Text up to 64 KiB from the request body is in the freshness buffer | Lexical search |
| `indexed` | Processing finished | Full-text, vector, and reranked search |
| `failed` | Processing failed; the bytes remain readable | Read the original, or call `reprocess` |

A write is committed before processing finishes. To wait for processing, send `Prefer: wait=N` on the write; see [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-write).

## Memory

A memory is a statement with a scope, a status, and a source: an account memory, a memory written as an Entry, or a fact distilled from an Entry. A distilled fact is not an Entry, and its id is not an Entry id. For scopes, statuses, and validity, see [The memory model](https://mirabase.io/developers/memory.md#model).

## Branches

A branch is a copy-on-write layer over a Space's main line, used as an Agent's workspace. Content on it creates no versions and is not processed. Each path becomes a new version only when merged into main. See [Branches and mounts](https://mirabase.io/developers/branches.md).

## Access control

Every request acts as a principal, a person or an Agent, carried by an API key. What a request may do depends on the capabilities the principal and the key both hold, the principal's role in the Space, and the read and write roots the Space owner set for the member. See [Permissions](https://mirabase.io/developers/permissions.md).

## Next steps

- [Files and versions](https://mirabase.io/developers/files.md): start by writing a file.
- [Retrieval and context](https://mirabase.io/developers/retrieval.md): search, context, and answers with citations.
- [Memory](https://mirabase.io/developers/memory.md): distill facts from conversations, then review, correct, and forget them.
