# Insight DB

Insight is a per-project local semantic index of the open project's files. Agents use it to find code and other content by meaning. The index stays on this computer with the app.

## Prerequisites

Assign an **Embeddings** model under **Settings → Active Models**. Without it, Insight does not index or search.

An **Image** model is optional. With one assigned, turn on **Settings → Projects → Insight DB → Image understanding** so images can be described and included in the index. Text indexing still runs if Image is unset; the status view may warn that images are unavailable.

Provider connections, capabilities, and role assignment are covered on [Models](/wiki/04-models).

## Insight DB view

With a project open, open **Insight DB** from the right-hand dash. The view shows:

| Field | Meaning |
|-------|---------|
| Status | `idle`, `syncing`, `chunking`, or `error` |
| Embedder | The embeddings model in use |
| Last sync | When the index last finished successfully |
| Files / Chunks / Size | How much of the project is in the index |
| Warning / error | Soft issues (for example images) or hard failures |

**Re-sync against embedding provider** rebuilds or refreshes the index for the open project.

Agents are the main way you discover project content through Insight. This view is for index health and manual sync.

## How agents use it

Insight is available when a project is open: **Agent**, **Discuss**, and **Plan** (including research). Home mode has no Insight.

Agents search the index by meaning to locate relevant files and passages, then continue from those hits. They can also check whether the index is ready, busy, or in error before relying on it.

Mode behavior and tools are detailed on [Agents](/wiki/05-agents).

## Chunks and conceptual mapping

Indexed files are split into **chunks**: meaning-bearing pieces that keep enough surrounding context for retrieval, including where in the file a hit came from.

Insight also builds a map of **conceptual relations** across the project. Agents use that map to move from a question to the right areas quickly.

When status shows **chunking**, that phase of indexing is in progress. **Files** and **Chunks** on the Insight DB view reflect how much of the project is currently indexed.

## Controlling what is indexed

Indexing walks the project tree and respects ignore rules so bulk or private paths stay out.

| File | Role |
|------|------|
| `.gitignore` | Patterns that exclude paths from git also exclude them from Insight, including nested `.gitignore` files with git-style scoping |
| `.insightignore` | Same pattern style as gitignore, applied only to Insight |

A path matched by either set is not ingested. Empty files are skipped until they have content.

Vendor and build trees are often already covered by `.gitignore`. Use `.insightignore` for Insight-only exclusions: generated artifacts, large assets you keep in git, or other paths that should stay out of the index.

## Where the index lives

The index is per-project machine data under `~/.insula/projects/...`, alongside plans and chats. It is not committed to the repository, not stored under project `.insula`, and not restored by cloud backup.

Cloud backup can sync Insight **preferences** (for example image understanding) with other app settings. The index itself stays on this machine. See [Settings spaces](/wiki/02-settings-spaces).

## Keeping the index current

Opening a project starts indexing. Later file changes trigger incremental updates; status may show `syncing` or `chunking` while work is in progress.

After you change the **Embeddings** model, or when Settings warns that vector length or size changed, use **Re-sync** on each project that uses Insight so the index matches the new model.

Changing the image model requires restarting the app before new image description uses the new assignment. The image-understanding toggle takes effect on the next project open or re-sync.

Forgetting a known project removes stored Insula project data, including the Insight index. Project source files on disk are left untouched.

## Related topics

- [What is Insula](/wiki/01-what-is-insula)
- [Settings spaces](/wiki/02-settings-spaces)
- [Models](/wiki/04-models)
- [Agents](/wiki/05-agents)
- [Remote servers](/wiki/08-remote-servers)