Data Storage¶

This page lists every location where Sidekick stores persistent data, what each location contains, and when it is written or read.

BN_USER_DIRECTORY/sidekick/¶

All plugin-level data lives under a single directory rooted at your Binary Ninja user directory:

$BN_USER_DIRECTORY/sidekick/

$BN_USER_DIRECTORY is the Binary Ninja user directory. To find its location, open the Binary Ninja Python console and run binaryninja.user_directory().

The full resolution order for the Sidekick root is:

$SIDEKICK_HOME environment variable, if set
$BN_USER_DIRECTORY/sidekick/ when running as the Binary Ninja plugin
~/.sidekick/ as a fallback (used by the standalone service or shell)

Directory layout¶

$BN_USER_DIRECTORY/sidekick/
├── config/
│   ├── completion_routing/
│   ├── mcp_tools_config.json
│   └── .meta.*.yaml
├── kernel/
│   └── .meta.*.yaml
├── data/
│   ├── workspaces.db
│   └── semantics.db
├── cache/
│   ├── models/
│   ├── embedding.lock
│   └── reranking.lock
└── filestore/
    ├── workspaces/
    │   └── <workspace-id>/
    │       └── processes/
    │           └── <process-id>/
    │               └── repos/
    │                   └── <resource-id>/
    └── app/
        └── processes/
            └── __global__/
                └── repos/
                    └── <resource-id>/

File and directory reference¶

Path	Type	Contents
`config/completion_routing/`	Directory	YAML key-value store for model endpoint and completion pool configurations. One `.yaml` file per stored object. Default endpoints and pools are installed here on first launch and can be freely customized.
`config/mcp_tools_config.json`	File	Optional. Configuration for external MCP tool servers. See Adding External Tools with MCP.
`config/.meta.*.yaml`	Files	Metadata for configuration objects stored in `config/`, including tool permission overrides (`application.tool_permissions.user_overrides.v1`).
`kernel/`	Directory	YAML key-value store for application-level kernel state. Holds the Library catalog (item names mapped to repository IDs) and other shared resources.
`kernel/.meta.*.yaml`	Files	Per-resource metadata for objects persisted in `kernel/`.
`data/workspaces.db`	SQLite	Primary workspace database. Contains all analysis data: chat threads, processes, indexes, code maps, notebook entries, task items, and transaction history. Namespaced by workspace ID.
`data/semantics.db`	SQLite	Semantic embedding vectors used for similarity search. Populated when semantic indexing is run on a binary. Shared across all workspaces.
`cache/models/`	Directory	Downloaded GGUF model files used by the local embedding and reranking sidecar processes.
`cache/embedding.lock`	JSON file	Sidecar lock file for the local embedding process. Records the process PID and reference-counted list of client PIDs. Created when the embedding sidecar starts; deleted when the last client exits.
`cache/reranking.lock`	JSON file	Sidecar lock file for the local reranking process. Same format and lifecycle as `embedding.lock`.
`filestore/`	Directory	On-disk storage for `FileRepository` resources (versioned file trees). Used by the Library to store Library item repositories, including scripts, agents, skills, and supporting files.
`filestore/workspaces/<id>/`	Directory	Filestore subtree scoped to a specific workspace.
`filestore/app/`	Directory	Filestore subtree for application-level resources shared across all workspaces (e.g., Library items).

workspaces.db — schema overview¶

workspaces.db is a SQLite database used by the kernel's SQLiteStorageProvider. All data is stored in two tables:

Table	Purpose
`storage`	Primary key-value store. Each row holds a `namespace`, a `key`, and a JSON-serialized `value`. The namespace is the workspace ID.
`metadata`	Per-key metadata (timestamps, type tags). Used during snapshot merge to compare record ages.

Every workspace's data is isolated under its own namespace (a UUID). The UUID is derived from the BNDB's global metadata key sidekick_workspace_uuid once the file is saved; before first save, a content hash is used as a transient ID. If you use File > Save As on an already-saved standalone .bndb, Sidekick writes a fresh workspace UUID for the new file and copies the existing workspace data into that new namespace instead of reusing the old one.

semantics.db — schema overview¶

semantics.db uses sqlite-vec for vector storage and similarity search. Key tables:

Table	Purpose
`binary_files`	One row per indexed binary, keyed by file path and content hash.
`embedding_records`	One row per embedding chunk, with text content, vector, and metadata (function address, symbol name, etc.).
`semantic_index_metadata`	Schema version and index generation counter.

Semantic indexes are regenerated locally and are not included in workspace snapshots (see Sharing Analysis Data).

BNDB metadata¶

Sidekick writes a small number of keys directly into the BNDB file's metadata store (accessible via Binary Ninja's store_metadata / query_metadata API). These keys are stored per binary view, not per Sidekick workspace.

Key	Scope	Contents
`sidekick_view_uuid`	Per-BinaryView	Persistent UUID assigned to each view type (e.g., `ELF`, `PE`) on first save. For standalone-file `Save As`, Sidekick writes fresh view UUIDs so the new file can fork its own workspace lineage.
`sidekick_workspace_uuid`	Per-file (global)	Persistent UUID for the file's workspace. Written via `database.write_global` on first save. For standalone-file `Save As`, Sidekick writes a new workspace UUID for the copied file.
`sidekick:portability.manifest`	Per-file or per-project	JSON manifest listing all workspace snapshots embedded in this BNDB or project.
`sidekick:portability.snapshot.<id>`	Per-file or per-project	Serialized `WorkspaceSnapshot` payload written by an export operation. One key per exported snapshot.

The sidekick_view_uuid and sidekick_workspace_uuid keys are written automatically when you save a .bndb file for the first time after opening it in Sidekick. Snapshot keys are written only when you explicitly export via Plugins > Sidekick > Import/Export Workspace... (see Sharing Analysis Data).

Note

Before a file is saved as a .bndb, Sidekick uses a transient workspace ID derived from a hash of the raw binary content. Data written under this transient ID is migrated to the persistent UUID automatically when you first save.

Note

On standalone .bndb files, File > Save As does not keep the old workspace identity. Sidekick generates new workspace and view UUIDs for the new file, copies the existing local workspace data into the new namespace, and leaves the original workspace data in place.

Binary Ninja settings.json¶

Sidekick stores its user-facing settings (API keys, model preferences, feature toggles) as sidekick.* keys inside Binary Ninja's own settings.json, located at:

$BN_USER_DIRECTORY/settings.json

These settings are documented in full on the Settings reference page.

Summary¶

Location	Moved with BNDB?	Backed up by BN?
`$BN_USER_DIRECTORY/sidekick/data/workspaces.db`	No	No
`$BN_USER_DIRECTORY/sidekick/data/semantics.db`	No	No
`$BN_USER_DIRECTORY/sidekick/config/`	No	No
`$BN_USER_DIRECTORY/sidekick/cache/`	No	No
`$BN_USER_DIRECTORY/sidekick/filestore/`	No	No
BNDB metadata (`sidekick_*` keys)	Yes — embedded in file	Yes — part of the .bndb
BNDB metadata (snapshot keys)	Yes — embedded in file	Yes — part of the .bndb
`$BN_USER_DIRECTORY/settings.json`	No	No

Because the primary analysis database (workspaces.db) is local-only, back up this file alongside your BNDB files if you want to preserve analysis history across machine migrations or re-installations. Alternatively, use the workspace export feature to embed a snapshot in the BNDB before moving the file.