hermes-skills/holographic-memory/SKILL.md

---
name: holographic-memory
description: "Configure and use Holographic as Hermes Agent's memory provider — local SQLite, FTS5 search, trust scoring, HRR algebra. Covers setup, migration from other providers, tool usage, and cleanup."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [holographic, memory, sqlite, local, migration, hermes]
    related_skills: [hermes-agent, hermes-config-bulk-update]
---

# Holographic Memory — Local SQLite Provider for Hermes Agent

Holographic is Hermes' zero-dependency local memory provider. It stores facts in a local SQLite database with FTS5 full-text search, trust scoring, and HRR (Holographic Reduced Representations) for compositional algebraic queries. No API keys, no daemon, no external services.

## When to Use

- Setting up Holographic as the memory provider
- Migrating from Hindsight (or any other provider) to Holographic
- Understanding Holographic's tools and capabilities
- Troubleshooting Holographic memory issues

**Memory system roles:** Holographic is the real-time, always-working, automatic memory provider — it handles cross-session recall via `fact_store`. The agent searches Holographic freely and automatically. Qdrant `memories` collection is a shared long-term archive across all profiles, auto-populated by a Holographic sync cron job. The agent does NOT search Qdrant unless explicitly told to — it's write-only from the agent's perspective. See `/home/n8n/workspace/general/new_holographic.md` for the full Holographic→Qdrant sync design.

## Quick Setup

```bash
# Interactive wizard (easiest)
hermes memory setup    # select "holographic"

# Or directly
hermes config set memory.provider holographic
```

Verify:
```bash
hermes memory status
# Should show: Provider: holographic, Status: available ✓
```

## Migration from Hindsight

Complete removal + switch to Holographic:

### 1. Switch provider
```bash
hermes config set memory.provider holographic
```

### 2. Kill Hindsight daemon
```bash
pkill -f hindsight
```

### 3. Uninstall Hindsight packages
```bash
pip uninstall hindsight hindsight-all hindsight-client -y
```

### 4. Clean profile directories
```bash
# Remove hindsight config dirs from all profiles
find ~/.hermes/profiles -maxdepth 3 -name 'hindsight' -type d -exec rm -rf {} + 2>/dev/null
# Remove hindsight log files
find ~/.hermes/profiles -maxdepth 3 -name 'hindsight-embed.log' -type f -exec rm -rf {} + 2>/dev/null
# Remove base hindsight dir
rm -rf ~/.hermes/hindsight
```

### 5. Strip HINDSIGHT env vars
```bash
# From base .env
sed -i '/^HINDSIGHT/d' ~/.hermes/.env
# From all profile .env files
for f in ~/.hermes/profiles/*/.env; do
  sed -i '/^HINDSIGHT/d' "$f"
done
```

### 6. Clean venv leftovers
```bash
# Remove site-packages
rm -rf ~/.hermes/hermes-agent/venv/lib/python3.11/site-packages/hindsight*
rm -rf ~/.hermes/hermes-agent/.venv/lib/python3.11/site-packages/hindsight*
# Remove binaries
rm -f ~/.hermes/hermes-agent/venv/bin/hindsight-*
rm -f ~/.hermes/hermes-agent/.venv/bin/hindsight-*
```

### 7. Verify
```bash
hermes memory status
grep -r 'HINDSIGHT' ~/.hermes/.env ~/.hermes/profiles/*/.env 2>/dev/null  # should return nothing
```

## Configuration

Config lives in `config.yaml` under `plugins.hermes-memory-store`:

| Key | Default | Description |
|-----|---------|-------------|
| `db_path` | `$HERMES_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) |

Minimal config — Holographic works out of the box with zero additional settings.

## Tools

Holographic provides two tools:

### `fact_store` — 9 actions

| Action | Description |
|--------|-------------|
| `add` | Store a new fact |
| `search` | FTS5 full-text search |
| `probe` | Entity-specific algebraic recall (all facts about a person/thing) |
| `related` | Find facts related to a given fact |
| `reason` | Compositional AND queries across multiple entities |
| `contradict` | Automated detection of conflicting facts |
| `update` | Update an existing fact |
| `remove` | Delete a fact |
| `list` | List all facts |

### `fact_feedback` — Trust scoring

Rate facts as helpful or unhelpful. Trust scores adjust asymmetrically:
- Helpful: +0.05
- Unhelpful: -0.10

This pushes the store toward self-correction over time.

## Unique Capabilities

- **`probe`** — entity-specific algebraic recall. Ask "what do we know about X?" and get all facts about that entity.
- **`reason`** — compositional AND queries. "What do we know about X AND Y?" combines multiple entity probes.
- **`contradict`** — automatic conflict detection. Finds facts that disagree with each other.
- **Trust scoring** — memories confirmed repeatedly gain weight; contradicted memories lose weight.

## Architecture

- **Storage:** Local SQLite with FTS5 extension
- **Retrieval:** HRR (Holographic Reduced Representations) — algebraic rather than pure semantic similarity
- **Dependencies:** None (SQLite is always available). NumPy optional for HRR algebra.
- **Cost:** Free
- **Data location:** `$HERMES_HOME/memory_store.db` (profile-scoped)

## Profile Isolation

Each profile gets its own SQLite database at `$HERMES_HOME/memory_store.db`. Since `$HERMES_HOME` differs per profile, data is naturally isolated.

## Comparison with Hindsight

| Dimension | Holographic | Hindsight |
|-----------|-------------|-----------|
| Storage | Local SQLite | Local PostgreSQL or Cloud |
| Dependencies | None | hindsight-client, daemon, LLM |
| Setup | One config line | Config + daemon + bank API |
| Retrieval | FTS5 + HRR algebra | Semantic + keyword + graph + temporal |
| Trust model | Explicit trust scoring | Observations + entity resolution |
| Best for | Local-only, zero-dependency | Rich structured memory, multi-agent |

## Pitfalls

- **Holographic is local-only.** No cloud sync, no multi-agent shared memory. Each profile is fully isolated.
- **No automatic fact extraction.** Unlike Hindsight (which extracts facts from conversation turns), Holographic relies on the agent explicitly using `fact_store add`. Set `auto_extract: true` to enable session-end extraction.
- **Trust scoring requires feedback.** Without `fact_feedback` calls, all facts stay at `default_trust` (0.5). The system doesn't self-correct without explicit feedback.
- **FTS5, not semantic search.** `fact_store search` uses SQLite FTS5 (full-text), not vector embeddings. Exact and near-exact matches work well; conceptual similarity does not.
- **No daemon to manage.** This is a feature, not a bug — but if you're used to checking daemon health, there's nothing to check. If memory isn't working, check `hermes memory status` and the SQLite file.

## References

- `references/hindsight-migration-checklist.md` — Step-by-step migration from Hindsight to Holographic
- `references/holographic-qdrant-sync.md` — Design for syncing Holographic facts to the shared Qdrant `memories` collection across all profiles