> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Providers

> External memory provider plugins — Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory

<Info>
  Commands, package names, and image names on this page come from the open-source project that Mibyan Desktop is built on, and can differ from the Mibyan Desktop installer. For the supported Mibyan install and update path, see [Install and update](/products/desktop-guide/install-and-update).
</Info>

Mibyan ships with 7 external memory provider plugins that give the agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md, and more (such as Hindsight) are available from the [plugin catalog](/desktop/user-guide/features/plugins). Only **one** external provider can be active at a time — the built-in memory is always active alongside it.

## Quick Start

```bash theme={null}
mibyan memory setup      # interactive picker + configuration
mibyan memory status     # check what's active
mibyan memory off        # disable external provider
```

You can also select the active memory provider via `mibyan plugins` → Provider Plugins → Memory Provider.

Or set manually in `~/.mibyan/config.yaml`:

```yaml theme={null}
memory:
  provider: openviking   # or honcho, mem0, holographic, retaindb, byterover, supermemory,
                         # or hindsight (plugin catalog — run `mibyan plugins install hindsight` first)
```

## How It Works

When a memory provider is active, Mibyan automatically:

1. **Injects provider context** into the system prompt (what the provider knows)
2. **Prefetches relevant memories** before each turn (background, non-blocking)
3. **Syncs conversation turns** to the provider after each response
4. **Extracts memories on session end** (for providers that support it)
5. **Mirrors built-in memory writes** to the external provider
6. **Adds provider-specific tools** so the agent can search, store, and manage memories

The built-in memory (MEMORY.md / USER.md) continues to work exactly as before. The external provider is additive.

## Available Providers

### Honcho

AI-native cross-session user modeling with dialectic reasoning, session-scoped context injection, semantic search, and persistent conclusions. Base context now includes the session summary alongside user representation and peer cards, giving the agent awareness of what has already been discussed.

| | |
| - | - |
| **Best for** | Multi-agent systems with cross-session context, user-agent alignment |
| **Requires** | `mibyan memory setup` prepares the Honcho SDK through PM; [API key](https://app.honcho.dev) or self-hosted instance |
| **Data storage** | Honcho Cloud or self-hosted |
| **Cost** | Honcho pricing (cloud) / free (self-hosted) |

**Tools (5):** `honcho_profile` (read/update peer card), `honcho_search` (semantic search), `honcho_context` (session context — summary, representation, card, messages), `honcho_reasoning` (LLM-synthesized), `honcho_conclude` (create/delete conclusions)

**Architecture:** Two-layer context injection — a base layer (session summary + representation + peer card, refreshed on `contextCadence`) plus a dialectic supplement (LLM reasoning, refreshed on `dialecticCadence`). The dialectic automatically selects cold-start prompts (general user facts) vs. warm prompts (session-scoped context) based on whether base context exists.

**Three orthogonal config knobs** control cost and depth independently:

* `contextCadence` — how often the base layer refreshes (API call frequency)
* `dialecticCadence` — how often the dialectic LLM fires (LLM call frequency)
* `dialecticDepth` — how many `.chat()` passes per dialectic invocation (1–3, depth of reasoning)

The auto-injected dialectic also scales its reasoning level by query length (longer query → deeper reasoning, capped at `reasoningLevelCap`); see [Query-Adaptive Reasoning Level](/desktop/user-guide/features/honcho#query-adaptive-reasoning-level).

**Setup Wizard:**

```bash theme={null}
mibyan memory setup        # select "honcho" — runs the Honcho-specific post-setup
```

The legacy `mibyan honcho setup` command still works (it now redirects to `mibyan memory setup`), but is only registered after Honcho is selected as the active memory provider.

**Headless / remote machines:** for cloud auth on a box without a browser (SSH, remote VM), pick **device** at the wizard's auth-method prompt. The CLI prints a short code and a verification link; open the link in a browser on any other machine, approve, and setup completes — no API key copy-paste. The wizard defaults to this option automatically when it detects no usable local browser.

**Config:** `$mibyan_HOME/honcho.json` (profile-local) or `~/.honcho/config.json` (global). Resolution order: `$mibyan_HOME/honcho.json` > `~/.mibyan/honcho.json` > `~/.honcho/config.json`. See the [config reference](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md) and the [Honcho integration guide](https://docs.honcho.dev/v3/guides/integrations/hermes).

<details>
  <summary>Full config reference</summary>

  | Key | Default | Description |
  | - | - | - |
  | `apiKey` | -- | API key from [app.honcho.dev](https://app.honcho.dev) |
  | `baseUrl` | -- | Base URL for self-hosted Honcho |
  | `peerName` | -- | User peer identity |
  | `aiPeer` | host key | AI peer identity (one per profile) |
  | `workspace` | host key | Shared workspace ID |
  | `contextTokens` | `null` (uncapped) | Token budget for auto-injected context per turn. Truncates at word boundaries |
  | `contextCadence` | `1` | Minimum turns between `context()` API calls (base layer refresh) |
  | `dialecticCadence` | `2` | Minimum turns between `peer.chat()` LLM calls. Recommended 1–5. Only applies to `hybrid`/`context` modes |
  | `dialecticDepth` | `1` | Number of `.chat()` passes per dialectic invocation. Clamped 1–3. Pass 0: cold/warm prompt, pass 1: self-audit, pass 2: reconciliation |
  | `dialecticDepthLevels` | `null` | Optional array of reasoning levels per pass, e.g. `["minimal", "low", "medium"]`. Overrides proportional defaults |
  | `dialecticReasoningLevel` | `'low'` | Base reasoning level: `minimal`, `low`, `medium`, `high`, `max` |
  | `dialecticDynamic` | `true` | When `true`, model can override reasoning level per-call via tool param |
  | `dialecticMaxChars` | `600` | Max chars of dialectic result injected into system prompt |
  | `recallMode` | `'hybrid'` | `hybrid` (auto-inject + tools), `context` (inject only), `tools` (tools only) |
  | `writeFrequency` | `'async'` | When to flush messages: `async` (background thread), `turn` (sync), `session` (batch on end), or integer N |
  | `saveMessages` | `true` | Whether to persist messages to Honcho API |
  | `observationMode` | `'directional'` | `directional` (all on) or `unified` (shared pool). Override with `observation` object |
  | `messageMaxChars` | `25000` | Max chars per message (chunked if exceeded) |
  | `dialecticMaxInputChars` | `10000` | Max chars for dialectic query input to `peer.chat()` |
  | `sessionStrategy` | `'per-directory'` | `per-directory`, `per-repo`, `per-session`, `global` |
  | `pinUserPeer` | `false` | Gateway only. When `true`, every non-agent gateway user collapses to `peerName`; the pin overrides all aliases |
  | `userPeerAliases` | `{}` | Gateway only. Maps runtime IDs to peers (`{"7654321": "alice"}`). Many-to-one |
  | `runtimePeerPrefix` | `""` | Gateway only. Namespaces unknown runtime IDs (`telegram_7654321`) when no alias matches |
</details>

<details>
  <summary>Minimal honcho.json (cloud)</summary>

  ```json theme={null}
  {
    "apiKey": "your-key-from-app.honcho.dev",
    "hosts": {
      "mibyan": {
        "enabled": true,
        "aiPeer": "mibyan",
        "peerName": "your-name",
        "workspace": "mibyan"
      }
    }
  }
  ```
</details>

<details>
  <summary>Minimal honcho.json (self-hosted)</summary>

  ```json theme={null}
  {
    "baseUrl": "http://localhost:8000",
    "hosts": {
      "mibyan": {
        "enabled": true,
        "aiPeer": "mibyan",
        "peerName": "your-name",
        "workspace": "mibyan"
      }
    }
  }
  ```
</details>

<Tip>
  **Migrating from `mibyan honcho`**

  If you previously used `mibyan honcho setup`, your config and all server-side data are intact. Just re-enable through the setup wizard again or manually set `memory.provider: honcho` to reactivate via the new system.
</Tip>

**Multi-peer setup:**

Honcho models conversations as peers exchanging messages — one user peer plus one AI peer per Mibyan profile, all sharing a workspace. The workspace is the shared environment: the user peer is global across profiles, each AI peer is its own identity. Every AI peer builds an independent representation / card from its own observations, so a `coder` profile stays code-oriented while a `writer` profile stays editorial against the same user.

The mapping:

| Concept | What it is |
| - | - |
| **Workspace** | Shared environment. All Mibyan profiles under one workspace see the same user identity. |
| **User peer** (`peerName`) | The human. Shared across profiles in the workspace. |
| **AI peer** (`aiPeer`) | One per Mibyan profile. Host key `mibyan` → default; `mibyan.<profile>` for others. |
| **Observation** | Per-peer toggles controlling what Honcho models from whose messages. `directional` (default, all four on) or `unified` (single-observer pool). |

### New profile, fresh Honcho peer

```bash theme={null}
mibyan profile create coder --clone
```

`--clone` creates a `mibyan.coder` host block in `honcho.json` with `aiPeer: "coder"`, shared `workspace`, inherited `peerName`, `recallMode`, `writeFrequency`, `observation`, etc. The AI peer is eagerly created in Honcho so it exists before the first message.

### Existing profiles, backfill Honcho peers

```bash theme={null}
mibyan honcho sync
```

Scans every Mibyan profile, creates host blocks for any profile without one, inherits settings from the default `mibyan` block, and creates the new AI peers eagerly. Idempotent — skips profiles that already have a host block.

### Per-profile observation

Each host block can override the observation config independently. Example: a code-focused profile where the AI peer observes the user but doesn't self-model:

```json theme={null}
"mibyan.coder": {
  "aiPeer": "coder",
  "observation": {
    "user": { "observeMe": true, "observeOthers": true },
    "ai":   { "observeMe": false, "observeOthers": true }
  }
}
```

**Observation toggles (one set per peer):**

| Toggle | Effect |
| - | - |
| `observeMe` | Honcho builds a representation of this peer from its own messages |
| `observeOthers` | This peer observes the other peer's messages (feeds cross-peer reasoning) |

Presets via `observationMode`:

* **`"directional"`** (default) — all four flags on. Full mutual observation; enables cross-peer dialectic.
* **`"unified"`** — user `observeMe: true`, AI `observeOthers: true`, rest false. Single-observer pool; AI models the user but not itself, user peer only self-models.

Server-side toggles set via the [Honcho dashboard](https://app.honcho.dev) win over local defaults — synced back at session init.

See the [Honcho page](/desktop/user-guide/features/honcho#observation-directional-vs-unified) for the full observation reference.

### Gateway identity mapping

The peer model above covers CLI, TUI, and desktop sessions, where every conversation resolves to `peerName`. The [gateway](/desktop/developer-guide/gateway-internals) adds a second axis: users arrive with platform-native runtime IDs (Telegram UID, Discord snowflake, Slack user), and three keys decide which peer each ID resolves to.

| Key | Effect |
| - | - |
| `pinUserPeer: true` | Every non-agent gateway user collapses to `peerName`. The pin is checked first, so it overrides all aliases — pick it only when no user-side identity needs its own peer |
| `userPeerAliases` | Maps specific runtime IDs to peers (`{"7654321": "alice"}`). The home for routing distinct identities — including agents that each carry their own peer |
| `runtimePeerPrefix` | Namespaces any unmapped runtime ID (`telegram_7654321`) so platforms with same-shaped IDs don't collide |

Off-gateway these keys do nothing. `mibyan memory setup` only prompts for them when it detects a connected gateway platform. See the [Honcho page](/desktop/user-guide/features/honcho#gateway-identity-mapping) for the resolver ladder and the setup flow.

<details>
  <summary>Full honcho.json example (multi-profile)</summary>

  ```json theme={null}
  {
    "apiKey": "your-key",
    "workspace": "mibyan",
    "peerName": "eri",
    "hosts": {
      "mibyan": {
        "enabled": true,
        "aiPeer": "mibyan",
        "workspace": "mibyan",
        "peerName": "eri",
        "recallMode": "hybrid",
        "writeFrequency": "async",
        "sessionStrategy": "per-directory",
        "observation": {
          "user": { "observeMe": true, "observeOthers": true },
          "ai": { "observeMe": true, "observeOthers": true }
        },
        "dialecticReasoningLevel": "low",
        "dialecticDynamic": true,
        "dialecticCadence": 2,
        "dialecticDepth": 1,
        "dialecticMaxChars": 600,
        "contextCadence": 1,
        "messageMaxChars": 25000,
        "saveMessages": true
      },
      "mibyan.coder": {
        "enabled": true,
        "aiPeer": "coder",
        "workspace": "mibyan",
        "peerName": "eri",
        "recallMode": "tools",
        "observation": {
          "user": { "observeMe": true, "observeOthers": false },
          "ai": { "observeMe": true, "observeOthers": true }
        }
      },
      "mibyan.writer": {
        "enabled": true,
        "aiPeer": "writer",
        "workspace": "mibyan",
        "peerName": "eri"
      }
    },
    "sessions": {
      "/home/user/myproject": "myproject-main"
    }
  }
  ```
</details>

See the [config reference](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md) and [Honcho integration guide](https://docs.honcho.dev/v3/guides/integrations/hermes).

***

### OpenViking

Context database by Volcengine (ByteDance) with filesystem-style knowledge hierarchy, tiered retrieval, and automatic memory extraction into 6 categories.

| | |
| - | - |
| **Best for** | Self-hosted knowledge management with structured browsing |
| **Requires** | OpenViking initialized, validated, and running |
| **Data storage** | Self-hosted (local or cloud) |
| **Cost** | Free (open-source, AGPL-3.0) |

**Tools (6):** `viking_search` (semantic search), `viking_read` (tiered: abstract/overview/full), `viking_browse` (filesystem navigation), `viking_remember` (store facts), `viking_forget` (delete a memory file by exact `viking://` URI), `viking_add_resource` (ingest URLs/docs)

**Setup:**

```bash theme={null}
# Prepare OpenViking first
openviking-server init
openviking-server doctor
openviking-server

# Then configure Mibyan
mibyan memory setup    # select "openviking"
# Or manually:
mibyan config set memory.provider openviking
```

`mibyan memory setup` can reuse or copy connection values from
`~/.openviking/ovcli.conf`. Manual setup uses the active profile's `.env` file;
for the default profile that is `~/.mibyan/.env`, and for named profiles use
`~/.mibyan/profiles/<profile>/.env`.

```text theme={null}
OPENVIKING_ENDPOINT=http://127.0.0.1:1933
# OPENVIKING_API_KEY=...
# OPENVIKING_ACCOUNT=default
# OPENVIKING_USER=default
```

OpenViking server settings live in `ov.conf` (`--config`,
`OPENVIKING_CONFIG_FILE`, or `~/.openviking/ov.conf`). Client connection values
live in `ovcli.conf` (`OPENVIKING_CLI_CONFIG_FILE` or
`~/.openviking/ovcli.conf`).

When the endpoint is local and nothing is listening, Mibyan starts
`openviking-server` in the background. That server gets your model-provider
keys (for its embedding and VLM models), your `HOME` and
`OPENVIKING_CONFIG_FILE`, but never bot, gateway or relay tokens, and not
Mibyan's `PYTHONPATH`. Put anything else the server needs in `ov.conf`.

**Key features:**

* Tiered context loading: L0 (\~100 tokens) → L1 (\~2k) → L2 (full)
* Automatic memory extraction on session commit (profile, preferences, entities, events, cases, patterns)
* `viking://` URI scheme for hierarchical knowledge browsing

`OPENVIKING_ACCOUNT` and `OPENVIKING_USER` are used for local/trusted mode.
Peer identity is optional. By default, Mibyan sends no peer ID and writes
explicit memories to `viking://user/<user>/memories/...`. Setup does not ask
for a peer ID. For separate assistant context, set
`memory.openviking.agent: work-assistant` in `config.yaml`.

Existing non-empty peer settings keep their peer-scoped writes and recall.
This includes `OPENVIKING_AGENT` and `actor_peer_id` or legacy `agent_id` in a
linked OpenViking config. Existing memories are not moved or deleted.
With no peer ID, default search covers user memory and existing peer memories
under the same OpenViking user. Old peer memories remain searchable at their
existing paths. Ranking and result limits determine which memories are returned.
Set `memory.openviking.agent: mibyan` to restore the old peer-scoped writes.
Memories written at user scope before this change stay there and remain
searchable. The setting changes future writes, not existing memory locations.

Mibyan sends `User-Agent: openviking-memory-mibyan/<version>` on OpenViking
requests. This standard harness identifier contains no per-user identifier and
does not add a separate request.

***

### Mem0

Server-side LLM fact extraction with semantic search, reranking, and automatic deduplication. Three connection modes: **Platform** (Mem0 Cloud), **self-hosted dashboard** (a Mem0 server you run via Docker), and **OSS** (Mem0 in-process with your own LLM + vector store).

| | |
| - | - |
| **Best for** | Hands-off memory management — Mem0 handles extraction automatically |
| **Requires** | `mibyan memory setup` prepares the Mem0 SDK through PM; API key (platform), a running Mem0 server (self-hosted dashboard), or an LLM + vector store (OSS) |
| **Data storage** | Mem0 Cloud (platform), your own Mem0 server (self-hosted dashboard), or in-process (OSS) |
| **Cost** | Mem0 pricing (platform) / free (self-hosted or OSS) |

The `mem0` SDK extra is excluded on native Windows ARM64. An external Mem0
server over HTTP is a separate mode; a remote service does not imply that the
in-process SDK runs on that target.

**Tools (4):** `mem0_search` (semantic search; optional reranking in platform mode, off by default), `mem0_add` (store verbatim facts), `mem0_update` (update by ID), `mem0_delete` (delete by ID)

**Setup (Platform):**

```bash theme={null}
mibyan memory setup    # select "mem0" → "Platform"
# Or manually:
mibyan config set memory.provider mem0
echo "MEM0_API_KEY=your-key" >> ~/.mibyan/.env
```

**Setup (OSS):**

```bash theme={null}
mibyan memory setup    # select "mem0" → "Open Source (self-hosted)"
# Or via flags:
mibyan memory setup mem0 --mode oss --oss-llm openai --oss-llm-key sk-... --oss-vector qdrant
```

Preview without writing files:

```bash theme={null}
mibyan memory setup mem0 --mode oss --oss-llm-key sk-... --dry-run
```

**Setup (Self-Hosted Dashboard):** connect to a Mem0 server you run via Docker (the dashboard's REST API):

```bash theme={null}
mibyan memory setup    # select "mem0" → "Self-hosted server"
# Or via flags:
mibyan memory setup mem0 --mode selfhosted --host http://localhost:8888 --api-key your-admin-api-key
```

Or configure manually — either as env vars:

```bash theme={null}
echo "MEM0_HOST=http://localhost:8888" >> ~/.mibyan/.env
echo "MEM0_API_KEY=your-admin-api-key" >> ~/.mibyan/.env
```

or in `mem0.json`:

```json theme={null}
{ "host": "http://localhost:8888", "api_key": "your-admin-api-key" }
```

The plugin authenticates with `X-API-Key` and uses the server's `/search` / `/memories` routes. `api_key` is optional (omit only for `AUTH_DISABLED` servers). Don't set `mode: oss` — it takes precedence over `host`.

**Config:** `$mibyan_HOME/mem0.json` (behavioral settings). Only the secret `MEM0_API_KEY` belongs in `~/.mibyan/.env`.

| Key | Default | Description |
| - | - | - |
| `mode` | `platform` | `platform` (Mem0 Cloud) or `oss` (self-managed, in-process) |
| `host` | — | Self-hosted Mem0 server URL (Docker dashboard). Routes over HTTP with `X-API-Key`; don't combine with `mode: oss` |
| `user_id` | `mibyan-user` | User identifier |
| `agent_id` | `mibyan` | Agent identifier |
| `rerank` | `false` | Rerank search results for relevance (platform mode only) |
| `sync_max_chars` | `450` | Per-message character cap applied before each turn is sent for fact extraction, cut at the last sentence boundary. The default fits 512-token embedders (Ollama `bge-small-zh-v1.5`, `all-minilm`); raise it (e.g. `6000`) for 8k-token embedders such as `text-embedding-3-small`, `jina-embeddings-v3` or `bge-m3` |

**OSS supported providers:**

| Component | Providers |
| - | - |
| LLM | openai, ollama |
| Embedder | openai, ollama |
| Vector Store | qdrant (local/server), pgvector |

**Switching modes:** Re-run `mibyan memory setup mem0 --mode <platform|selfhosted|oss>` or edit `mem0.json` directly.

***

### Hindsight

<Info>
  **Plugin catalog**

  Hindsight is maintained by [vectorize-io](https://github.com/vectorize-io/hindsight) and installed from the [plugin catalog](/desktop/user-guide/features/plugins) rather than bundled with Mibyan. Setup details live in the upstream docs: [hindsight.vectorize.io/sdks/integrations/mibyan](https://hindsight.vectorize.io/sdks/integrations/hermes).
</Info>

Long-term memory with knowledge graph, entity resolution, and multi-strategy retrieval. The `hindsight_reflect` tool provides cross-memory synthesis that no other provider offers. Automatically retains full conversation turns (including tool calls) with session-level document tracking.

| | |
| - | - |
| **Best for** | Knowledge graph-based recall with entity relationships |
| **Requires** | `mibyan plugins install hindsight`. Cloud: API key from [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io). Local: LLM API key (OpenAI, Groq, OpenRouter, etc.) |
| **Data storage** | Hindsight Cloud, local embedded PostgreSQL, or an external local Hindsight server |
| **Cost** | Hindsight pricing (cloud) or free (local) |

**Tools:** `hindsight_retain` (store with entity extraction), `hindsight_recall` (multi-strategy search), `hindsight_reflect` (cross-memory synthesis)

**Setup:**

```bash theme={null}
mibyan plugins install hindsight   # from the plugin catalog
mibyan memory setup                # select "hindsight"
# Or manually:
mibyan config set memory.provider hindsight
echo "HINDSIGHT_API_KEY=your-key" >> ~/.mibyan/.env
```

The plugin lands in `~/.mibyan/plugins/hindsight/` (per profile home) and is enabled under `plugins.enabled` in `config.yaml`. `mibyan memory setup`, `mibyan memory status`, `mibyan plugins list` and the dashboard Memory settings all work with the catalog-installed plugin. In local embedded mode the plugin installs `hindsight-all` on first use through Mibyan' lazy-install path, which honours `security.allow_lazy_installs`.

**Local mode UI:** `hindsight-embed -p mibyan ui start`

**Config:** `$mibyan_HOME/hindsight/config.json`

| Key | Default | Description |
| - | - | - |
| `mode` | `cloud` | `cloud`, `local_embedded`, or `local_external` |
| `bank_id` | `mibyan` | Memory bank identifier |
| `recall_budget` | `mid` | Recall thoroughness: `low` / `mid` / `high` |
| `memory_mode` | `hybrid` | `hybrid` (context + tools), `context` (auto-inject only), `tools` (tools only) |
| `auto_retain` | `true` | Automatically retain conversation turns |
| `auto_recall` | `true` | Automatically recall memories before each turn |
| `retain_async` | `true` | Process retain asynchronously on the server |
| `retain_context` | `conversation between Mibyan and the User` | Context label for retained memories |
| `retain_tags` | — | Default tags applied to retained memories; merged with per-call tool tags |
| `retain_source` | — | Optional `metadata.source` attached to retained memories |
| `retain_user_prefix` | `User` | Label used before user turns in auto-retained transcripts |
| `retain_assistant_prefix` | `Assistant` | Label used before assistant turns in auto-retained transcripts |
| `recall_tags` | — | Tags to filter on recall |

See the [upstream Mibyan integration docs](https://hindsight.vectorize.io/sdks/integrations/hermes) for the full configuration reference.

#### Migrating from bundled Hindsight

Hindsight used to ship inside the Mibyan tree (and as the `mibyan-agent[hindsight]` pip extra). If your `config.yaml` already has `memory.provider: hindsight`, there is nothing to do for most users:

* `mibyan update` installs the catalog plugin into every profile home that names the provider (this runs even when `security.allow_lazy_installs` is `false`).
* If the plugin is still missing on the first agent start (`mibyan chat`, the gateway, …), Mibyan installs it and prints `✓ Memory provider 'hindsight' moved out of core — installed its plugin from the catalog (your memory.hindsight settings and data are unchanged).`
* With `security.allow_lazy_installs: false`, the agent-start path instead logs one line — ``Memory provider 'hindsight' is not installed; security.allow_lazy_installs is off — run `mibyan plugins install hindsight`.`` — and you run `mibyan plugins install hindsight` yourself.

What changes on disk: the plugin appears in `~/.mibyan/plugins/hindsight/` and `config.yaml` gains `plugins.enabled: [hindsight]`. `memory.provider`, `memory.hindsight.*`, `$mibyan_HOME/hindsight/config.json`, `HINDSIGHT_API_KEY` in `.env` and your memory bank data are untouched. Verify with `mibyan memory status` (provider active) and `mibyan plugins list` (plugin installed and enabled).

***

### Holographic

Local SQLite fact store with FTS5 full-text search, trust scoring, and HRR (Holographic Reduced Representations) for compositional algebraic queries.

| | |
| - | - |
| **Best for** | Local-only memory with advanced retrieval, no external dependencies |
| **Requires** | Nothing (SQLite is always available). NumPy optional for HRR algebra. |
| **Data storage** | Local SQLite |
| **Cost** | Free |

**Tools:** `fact_store` (9 actions: add, search, probe, related, reason, contradict, update, remove, list), `fact_feedback` (helpful/unhelpful rating that trains trust scores)

**Setup:**

```bash theme={null}
mibyan memory setup    # select "holographic"
# Or manually:
mibyan config set memory.provider holographic
```

**Config:** `config.yaml` under `plugins.mibyan-memory-store`

| Key | Default | Description |
| - | - | - |
| `db_path` | `$mibyan_HOME/memory_store.db` | SQLite database path |
| `auto_extract` | `false` | Auto-extract facts at session end |
| `default_trust` | `0.5` | Default trust score (0.0–1.0) |

**Unique capabilities:**

* `probe` — entity-specific algebraic recall (all facts about a person/thing)
* `reason` — compositional AND queries across multiple entities
* `contradict` — automated detection of conflicting facts
* Trust scoring with asymmetric feedback (+0.05 helpful / -0.10 unhelpful)

***

### RetainDB

Cloud memory API with hybrid search (Vector + BM25 + Reranking), 7 memory types, and delta compression.

| | |
| - | - |
| **Best for** | Teams already using RetainDB's infrastructure |
| **Requires** | RetainDB account + API key |
| **Data storage** | RetainDB Cloud |
| **Cost** | \$20/month |

**Tools (10):** `retaindb_profile` (user profile), `retaindb_search` (semantic search), `retaindb_context` (task-relevant context), `retaindb_remember` (store with type + importance), `retaindb_forget` (delete memories), plus file tools: `retaindb_upload_file`, `retaindb_list_files`, `retaindb_read_file`, `retaindb_ingest_file`, `retaindb_delete_file`

**Setup:**

```bash theme={null}
mibyan memory setup    # select "retaindb"
# Or manually:
mibyan config set memory.provider retaindb
echo "RETAINDB_API_KEY=your-key" >> ~/.mibyan/.env
```

***

### ByteRover

Persistent memory via the `brv` CLI — hierarchical knowledge tree with tiered retrieval (fuzzy text → LLM-driven search). Local-first with optional cloud sync.

| | |
| - | - |
| **Best for** | Developers who want portable, local-first memory with a CLI |
| **Requires** | ByteRover CLI (`npm install -g byterover-cli` or [install script](https://byterover.dev)) |
| **Data storage** | Local (default) or ByteRover Cloud (optional sync) |
| **Cost** | Free (local) or ByteRover pricing (cloud) |

**Tools:** `brv_query` (search knowledge tree), `brv_curate` (store facts/decisions/patterns), `brv_status` (CLI version + tree stats)

**Setup:**

```bash theme={null}
# Install the CLI first
curl -fsSL https://byterover.dev/install.sh | sh

# Then configure Mibyan
mibyan memory setup    # select "byterover"
# Or manually:
mibyan config set memory.provider byterover
```

**Key features:**

* Automatic pre-compression extraction (saves insights before context compression discards them)
* Knowledge tree stored at `$mibyan_HOME/byterover/` (profile-scoped)
* SOC2 Type II certified cloud sync (optional)

***

### Supermemory

Semantic long-term memory with profile recall, semantic search, explicit memory tools, and per-turn conversation capture (one document per session per 4-hour window).

| | |
| - | - |
| **Best for** | Semantic recall with user profiling and session-level graph building |
| **Requires** | `mibyan memory setup` prepares the Supermemory SDK through PM; [cloud API key](http://app.supermemory.ai/integrations?connect=hermes), or a [self-hosted server](https://supermemory.ai/docs/self-hosting/overview) |
| **Data storage** | Supermemory Cloud or self-hosted |
| **Cost** | Supermemory pricing (cloud) / free (self-hosted) |

**Tools:** `supermemory_store` (save explicit memories), `supermemory_search` (semantic similarity search), `supermemory_forget` (forget by ID or best-match query), `supermemory_profile` (persistent profile + recent context)

**Setup:**

```bash theme={null}
mibyan memory setup    # select "supermemory"
# Or manually:
mibyan config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.mibyan/.env
```

Self-hosted setup:

```bash theme={null}
npx supermemory local
```

Before running `mibyan memory setup`, set `base_url` in
`$mibyan_HOME/supermemory.json`:

```json theme={null}
{
  "base_url": "http://localhost:6767"
}
```

Then run `mibyan memory setup` and enter the API key printed by the local
server. Configuring the endpoint first ensures the setup connection probe also
stays local.

**Config:** `$mibyan_HOME/supermemory.json`

| Key | Default | Description |
| - | - | - |
| `base_url` | `https://api.supermemory.ai` | API endpoint for hosted or self-hosted Supermemory. Takes priority over `SUPERMEMORY_BASE_URL`. |
| `container_tag` | `mibyan` | Container tag used for search and writes. Supports `{identity}` template for profile-scoped tags. |
| `auto_recall` | `true` | Inject relevant memory context before turns |
| `auto_capture` | `true` | Store cleaned user-assistant turns after each response |
| `max_recall_results` | `10` | Max recalled items to format into context |
| `profile_frequency` | `50` | Include profile facts on first turn and every N turns |
| `capture_mode` | `all` | Skip tiny or trivial turns by default |
| `search_mode` | `hybrid` | Search mode: `hybrid`, `memories`, or `documents` |
| `api_timeout` | `5.0` | Timeout for SDK requests |

**Environment variables:** `SUPERMEMORY_API_KEY` (required), `SUPERMEMORY_BASE_URL` (compatibility fallback when `base_url` is not configured), `SUPERMEMORY_CONTAINER_TAG` (overrides config).

Base URL precedence is `supermemory.json` → `SUPERMEMORY_BASE_URL` → `https://api.supermemory.ai`. SDK operations and setup/status probes all use the resolved endpoint.

**Key features:**

* Automatic context fencing — strips recalled memories from captured turns to prevent recursive memory pollution
* Per-turn capture — each completed turn is written as it happens, one document per session per 4-hour window
* Failed turn writes are retried (at-least-once) on the next turn, session end, `/reset`, or shutdown
* End-to-end self-hosted routing — SDK and probe requests use the same configured endpoint
* Profile facts injected on first turn and at configurable intervals
* **Profile-scoped containers** — use `{identity}` in `container_tag` (e.g. `mibyan-{identity}` → `mibyan-coder`) to isolate memories per Mibyan profile
* **Multi-container mode** — enable `enable_custom_container_tags` with a `custom_containers` list to let the agent read/write across named containers. Automatic operations stay on the primary container.

<details>
  <summary>Multi-container example</summary>

  ```json theme={null}
  {
    "container_tag": "mibyan",
    "enable_custom_container_tags": true,
    "custom_containers": ["project-alpha", "shared-knowledge"],
    "custom_container_instructions": "Use project-alpha for coding context."
  }
  ```
</details>

**Support:** [Discord](https://supermemory.link/discord) · [support@supermemory.com](mailto:support@supermemory.com)

### Memori

Structured long-term memory using Memori Cloud, with background completed-turn capture, tool-aware turn context, and explicit recall tools for facts, summaries, quota, signup, and feedback.

| | |
| - | - |
| **Best for** | Agent-controlled recall with structured project and session attribution |
| **Requires** | Externally supplied `mibyan-memori` CLI and provider integration + [Memori API key](https://app.memorilabs.ai/signup) |
| **Data storage** | Memori Cloud |
| **Cost** | Memori pricing |

**Tools:** `memori_recall` (search long-term memory), `memori_recall_summary` (summarized context), `memori_quota` (usage/quota), `memori_signup` (request signup email), `memori_feedback` (send integration feedback)

**Setup:**

`mibyan-memori` is an external integration, not a managed PM tool name. Follow
its publisher's instructions to install the CLI in an independent environment.
Before running its installer, confirm that it targets the intended Mibyan home
and supplies a provider with declared Python dependencies. Do not let an external
installer pip-install into Mibyan's selected environment. CLI availability alone
does not make the Python provider available inside Mibyan; an entry-point-only
distribution needs an owner-managed build that includes it.

```bash theme={null}
# Run only after confirming the external installer's integration contract above.
mibyan-memori install
mibyan config set memory.provider memori
mibyan memory setup
```

If the installer does not support PM-managed directory-provider admission, ask
the publisher for that integration rather than inventing a `mibyan pm install`
package command. Restart Mibyan after successful dependency preparation.

***

## Provider Comparison

| Provider | Storage | Cost | Tools | Dependencies | Unique Feature |
| - | - | - | - | - | - |
| **Honcho** | Cloud | Paid | 5 | `honcho-ai` | Dialectic user modeling + session-scoped context |
| **OpenViking** | Self-hosted | Free | 6 | `openviking` + server | Filesystem hierarchy + tiered loading |
| **Mem0** | Cloud/Self-hosted | Free/Paid | 4 | `mem0ai` | Server-side LLM extraction + self-hosted/OSS modes |
| **Hindsight** (plugin catalog) | Cloud/Local | Free/Paid | 3 | `mibyan plugins install hindsight` | Knowledge graph + reflect synthesis |
| **Holographic** | Local | Free | 2 | None | HRR algebra + trust scoring |
| **RetainDB** | Cloud | \$20/mo | 10 | `requests` | Delta compression |
| **ByteRover** | Local/Cloud | Free/Paid | 3 | `brv` CLI | Pre-compression extraction |
| **Supermemory** | Cloud/Self-hosted | Free/Paid | 4 | `supermemory` | Context fencing + session graph ingest + multi-container |
| **Memori** | Cloud | Free/Paid | 5 | `mibyan-memori` | Tool-aware memory + structured recall |

## Profile Isolation

Each provider's data is isolated per [profile](/desktop/user-guide/profiles):

* **Local storage providers** (Holographic, ByteRover) use `$mibyan_HOME/` paths which differ per profile
* **Config file providers** (Honcho, Mem0, Hindsight, Supermemory) store config in `$mibyan_HOME/` so each profile has its own credentials
* **Cloud providers** (RetainDB) auto-derive profile-scoped project names
* **Env var providers** (OpenViking) are configured via each profile's `.env` file

## Providers Moving to the Plugin Catalog

Memory providers are moving out of the Mibyan tree into their maintainers' own repositories,
published through the [plugin catalog](/desktop/user-guide/features/plugins) — Hindsight is the first (see
[Migrating from bundled Hindsight](#migrating-from-bundled-hindsight)). Nothing changes for you: the
provider name, your `memory.<name>` settings, its data directory and its tools stay the same.
When a provider you have configured stops shipping with Mibyan, `mibyan update` installs its
catalog plugin for every profile that names it; if you update through the Desktop app, the
agent does the same the first time it starts (unless `security.allow_lazy_installs` is
`false`, in which case it logs the `mibyan plugins install <name>` one-liner instead).

## Building a Memory Provider

See the [Developer Guide: Memory Provider Plugins](/desktop/developer-guide/memory-provider-plugin) for how to create your own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.