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(). By default it is ~/Library/Application Support/Binary Ninja on macOS, ~/.binaryninja on Linux, and %APPDATA%\Binary Ninja on Windows.

Sidekick always stores its data in $BN_USER_DIRECTORY/sidekick/. The SIDEKICK_HOME environment variable does not change this location; the one exception is downloaded embedding models (see cache/models/ below).

Directory layout¶

$BN_USER_DIRECTORY/sidekick/
├── actors/
│   ├── application/
│   └── session/
├── config/
│   ├── completion_routing/
│   ├── mcp_tools_config.json
│   └── .meta.*.yaml
├── mcp_servers/
│   └── mcp_test_server.py
├── data/
│   ├── workspaces.db
│   ├── kernel.db
│   ├── search.db
│   └── semantics.db
├── cache/
│   ├── artifacts/
│   ├── models/
│   ├── embedding.lock
│   └── reranking.lock
└── filestore/
    ├── workspaces/
    │   └── <workspace-id>/
    │       └── processes/
    │           └── <process-id>/
    │               ├── repos/
    │               │   └── <resource-id>/
    │               └── script_executions/
    │                   └── <execution-id>/
    └── app/
        └── processes/
            └── __global__/
                ├── repos/
                │   └── <resource-id>/
                └── script_executions/
                    └── <execution-id>/

File and directory reference¶

Path	Type	Contents
`actors/`	Directory	Background actor definitions (`actor.*.yaml`). Sidekick installs its bundled actors here at startup and replaces a bundled actor file when a newer version ships, so local edits to bundled actors can be overwritten on upgrade. Copy a bundled actor under a new name before customizing it.
`config/completion_routing/`	Directory	YAML key-value store for model endpoint and completion pool configurations (`endpoint..yaml`, `completer_pool..yaml`). Default endpoints and pools are installed here at startup if missing. Your edits are preserved; a default you delete is restored on the next launch.
`config/mcp_tools_config.json`	File	Configuration for external MCP tool servers. Created on first run with a disabled sample server entry and never overwritten once it exists. See Adding External Tools with MCP.
`config/.meta.*.yaml`	Files	Metadata for configuration objects stored in `config/`, including your application-wide tool permission settings.
`mcp_servers/mcp_test_server.py`	File	Bundled sample MCP server, copied here on first run. See Adding External Tools with MCP.
`data/kernel.db`	SQLite	Application-level state shared by all workspaces, including the Library catalog and the metadata of Library item repositories. File contents of Library items are stored under `filestore/app/`.
`data/search.db`	SQLite	Search index behind the Sidekick tab Search box. Holds a searchable copy of content from all workspaces. It is rebuilt automatically, so the file can be deleted safely. Shared across all workspaces.
`data/workspaces.db`	SQLite	Primary workspace database. Contains all analysis data: chat threads, processes, indexes, code maps, notebook entries, task items, transaction history, agent request inputs, and pending delegation/reply state. Namespaced by workspace ID. Active runtime state is excluded from workspace sharing.
`data/semantics.db`	SQLite	Semantic embedding vectors used for similarity search. Created when semantic indexing is enabled and run on a binary. Shared across all workspaces.
`cache/artifacts/<id>/`	Directory	Read-only local copies of workspace artifact files, written when you open, show in the file manager, or run an artifact. Each artifact version gets its own folder. Edits to these copies do not reach Sidekick. The folder is not cleaned automatically and is safe to delete.
`cache/models/`	Directory	Downloaded embedding model files, used only by Sidekick's optional built-in embedding provider. Unlike the rest of this tree, this folder is `$SIDEKICK_HOME/cache/models/` (default `~/.sidekick/cache/models/`), even inside Binary Ninja.
`cache/embedding.lock`	JSON file	Lock file for the local embedding process. Present only while semantic indexing is enabled and Sidekick is running that process. Removed when the last Binary Ninja instance using it exits.
`cache/reranking.lock`	JSON file	Lock file for the local reranking process. Same format and lifecycle as `embedding.lock`.
`filestore/`	Directory	On-disk storage for versioned file trees and script working files. Used by the Library to store Library item repositories, including scripts, agents, skills, and supporting files. If the folder cannot be written, Sidekick falls back to a `sidekick-filestore` folder in the system temp directory.
`filestore/workspaces/<id>/`	Directory	Filestore subtree scoped to a specific workspace. Deleted with its 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. Its tables are:

Table	Purpose
`storage`	Primary key-value store. Each row holds a workspace ID, a key, a JSON value, and created/updated timestamps.
`metadata`	Per-workspace auxiliary values, such as the source file or project path and name, workspace name, and the workspace's tool permission settings.
`project_workspaces`	Named workspaces (investigations) of each Binary Ninja project. Delete a workspace from the Sidekick tab to remove its membership and stored data; export it first to keep a snapshot.
`project_workspace_selection`	The workspace last selected in each Binary Ninja project.

While Sidekick is running, matching -wal and -shm files may appear beside workspaces.db, kernel.db, and search.db.

Every workspace's data is isolated under its own namespace (a UUID). The UUID is a random ID assigned when the file is opened. It is written into the BNDB's global metadata key sidekick_workspace_uuid when you first save, so the workspace keeps the same ID before and after the first save. Opening two identical binaries creates two independent workspaces. 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 view, keyed by workspace ID and binary view ID.
`embeddings`	One row per embedding chunk, with its text content, object ID, and object type.
`embedding_vectors`	The sqlite-vec table holding each chunk's vector.
`object_fingerprints`	Content and model hashes used to detect stale embeddings.
`semantic_index_metadata`	Schema version, embedding dimensions, model fingerprint, and index generation.

A single file serves all workspaces, with rows scoped by workspace ID. If you change the embedding model (or its vector size), Sidekick discards and rebuilds the whole index.

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	UUID of each view type (e.g., `ELF`, `PE`), assigned when the view is first opened and saved into the BNDB the first time you save. Standalone files only. 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)	UUID of the file's workspace, assigned when the file is opened and written the first time you save. Standalone files only. Files inside a Binary Ninja project are not stored in this key. A project can have several workspaces, all tracked in `workspaces.db`. 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 workspace snapshot written by an export operation. One key per exported snapshot.

The sidekick_view_uuid and sidekick_workspace_uuid keys are written when you save a standalone .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 Data... (see Sharing Analysis Data).

Note

Before a file is saved as a .bndb, its workspace has a random temporary ID, and the workspace's data lives in workspaces.db under that ID. The first save keeps the same ID, so nothing is moved or rewritten. If you close a file that has never been saved as a .bndb, Sidekick deletes that workspace's data. If the workspace contains your own chats or other work, Sidekick first shows a Close Transient Sidekick Workspace? confirmation; a workspace with nothing in it is removed without a prompt.

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 settings (service connection and API key, execution timeouts, analysis options, semantic indexing options) as user-scope 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.

The out-of-credits notification preference and last notification time are also stored here, so both persist across restarts. The timestamp is maintained automatically and hidden from the Settings UI.

Summary¶

Location	Moved with BNDB?	Backed up by BN?
`$BN_USER_DIRECTORY/sidekick/data/workspaces.db`	No	No
`$BN_USER_DIRECTORY/sidekick/data/kernel.db`	No	No
`$BN_USER_DIRECTORY/sidekick/data/search.db`	No	No
`$BN_USER_DIRECTORY/sidekick/data/semantics.db`	No	No
`$BN_USER_DIRECTORY/sidekick/actors/`	No	No
`$BN_USER_DIRECTORY/sidekick/mcp_servers/`	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
User-chosen `*.sidekick-workspace.json` export file (wherever you save it)	No	No
`$BN_USER_DIRECTORY/settings.json`	No	No

Because the primary analysis database (workspaces.db) is local-only, copy data/workspaces.db (with any -wal and -shm files, while Binary Ninja is closed) and the filestore/ folder together if you want to preserve analysis history across machine migrations or re-installations. Also copy data/kernel.db if you want to keep Library items (their file contents live under filestore/app/). Alternatively, use Plugins > Sidekick > Import/Export Workspace Data... to embed a snapshot in the BNDB (or project) before moving the file, or right-click a workspace row in the Sidekick tab and choose Export Workspace… to save a standalone .sidekick-workspace.json file (see Sharing Analysis Data).

Lifecycle and deletion¶

Workspaces for raw binaries that have never been saved as a .bndb are temporary. Sidekick deletes their data when the file closes, after a Close Transient Sidekick Workspace? confirmation if the workspace contains your own chats or other work. Save as a .bndb to keep it.

Workspaces for saved files and projects stay in workspaces.db after the file is closed until you remove them with Delete Workspace… in the Sidekick tab row menu. That action is not available while the workspace is open. It deletes the workspace's records, filestore folder, semantic index entries, and search index entries. Deleting a BNDB does not delete its workspace data.

To clear only the embeddings for a workspace, use Plugins > Sidekick > Reset Semantic Index for Workspace....