# Cortex Knowledge Engine Debian installer · 1.3.4

Transfer the `.run` file to a fresh **Debian 13 x86-64 VM or physical machine** and run it with `sudo`. The `.tar.gz` provides the same bundle for inspection/manual extraction. The wizard asks for the machine's address, UI access mode/port and an optional existing SSH account for agent access. Proxmox is not required; Debian VMs on Proxmox are suitable.

This is a portable application installer archive, not a `.deb`. Setup downloads its dependencies. It is not an offline installation image or an upgrade installer.

## Requirements

- Debian 13 (Trixie), amd64/x86-64, with systemd running.
- At least 8 GiB RAM; 4 CPUs and 12 GiB RAM recommended.
- At least 12 GiB free space under `/var`; 25 GiB recommended.
- Root or sudo access, internet access and a stable IP/DNS name.
- Free ports 5432, 6333, 7474, 7687 and 8088 on loopback; chosen UI port defaults to 8090.
- A fresh host: existing Cortex directories, accounts or services cause setup to stop instead of overwriting them.

## Transfer and install

From your workstation, transfer the executable installer and checksum using SFTP or SCP:

```sh
scp memory-cortex-debian-1.3.4.run memory-cortex-debian-1.3.4.run.sha256 user@debian-machine:/tmp/
```

On the **Debian machine**, run:

```sh
cd /tmp
sha256sum -c memory-cortex-debian-1.3.4.run.sha256
chmod +x memory-cortex-debian-1.3.4.run
sudo ./memory-cortex-debian-1.3.4.run
```

The `.run` verifies and extracts its embedded archive into a private temporary directory, launches the wizard and cleans up the temporary files. Resume uses `sudo ./memory-cortex-debian-1.3.4.run --resume`.

Alternatively, transfer the `.tar.gz` and `.sha256`, verify them with `sha256sum -c`, extract the archive, enter its directory and run `sudo ./install.sh`.

Checksums detect transfer errors; they are not a publisher signature. Verify the archive came from the intended source before running it as root.

The wizard shows its settings before installing. Database passwords and separate read/write/admin API keys are generated automatically; setup does not ask you to paste secrets into chat. No hostname, credentials, personal notes or database contents from the original deployment are bundled.

`./install.sh --plan` previews the questions and settings without changing the host. `sudo ./install.sh --check` checks the fresh-host requirements without installing. On a minimal Debian system lacking Python, a normal install first installs Debian's Python 3 package to run the wizard.

## What is installed

- Cortex API on `127.0.0.1:8088`, authenticated with role-specific keys.
- Memories UI: browse, search, edit, forget/restore, and provenance.
- Animated Universe graph of recorded links and associations.
- Markdown vault, Git history, local CPU embeddings (`all-MiniLM-L6-v2`).
- PostgreSQL 16, Qdrant 1.18.0 and Neo4j 5.26 Community in Docker, bound to loopback with persistent volumes.
- API, worker, watcher, datastore and UI services supervised by systemd.
- A restricted PostgreSQL application login instead of a superuser login.
- An optional restricted SSH/sudo MCP command for agents.

Cortex supplies memory tools, not a chat LLM. Configure the agent's Ollama/OpenAI/other LLM separately. The vault is a directory of plain Markdown files.

Local-only UI is the default. Access it over an SSH tunnel:

```sh
ssh -L 8090:127.0.0.1:8090 user@debian-machine
```

Then open `http://127.0.0.1:8090/memories`. For a custom UI port, use that port on both sides of the tunnel.

Trusted-LAN mode binds the UI to all IPv4 interfaces. The UI has no user login: anyone who can reach it can read, edit, forget and restore memories. Choose this mode only on the network where that access is intended. The REST API and databases stay on loopback; setup does not open firewall ports or add port forwarding. For remote access, use a tunnel/VPN or a separately configured authenticated HTTPS proxy.

## Administration and recovery

```sh
sudo cortexctl status
sudo cortexctl health
sudo cortexctl restart
sudo cortexctl stop
sudo cortexctl start
sudo cortexctl credentials
sudo journalctl -u cortex-api -u cortex-worker -u cortex-dashboard --since today
```

Only `credentials` intentionally prints API keys. Keep its output private.

Locations:

- Application and virtualenv: `/opt/memory-cortex` (root-owned code).
- Protected application configuration: `/opt/memory-cortex/.env` (root and service group only).
- Datastore bootstrap credentials: `/opt/memory-cortex/.datastores.env` (root only; not readable by the Cortex service user).
- Vault and Git history: `/var/lib/memory-cortex/vault`.
- Provenance and Forgotten recovery copies: `/var/lib/memory-cortex/vault-metadata`.
- Embedding cache: `/var/lib/memory-cortex/model-cache`.
- Installer checkpoints: `/var/lib/memory-cortex-installer/state.json` (root-only).
- Docker volumes: project `memory-cortex`.

If setup fails or is interrupted, fix the reported problem and run the **same bundle** again with:

```sh
sudo ./install.sh --resume
```

Setup preserves generated credentials and completed phases. Resume is not an upgrade/migration command. No automatic uninstall or data purge is included. Forget is recoverable removal from active memory; Git history and recovery copies are retained.

Back up the vault **and vault-metadata**, protected configuration, installer state, and consistent PostgreSQL/Neo4j/Qdrant data snapshots. The installer configures private daily application backups. Keep your VM backups as a separate recovery layer.

## Agent connection

If you enabled an existing SSH account during setup, the generated sudoers rule allows only this no-argument command as the unprivileged `cortex` service user:

```sh
ssh user@debian-machine sudo -n -u cortex /usr/local/libexec/cortex-mcp
```

The command runs the stdio MCP server with server-side credentials. It exposes all Cortex MCP tools; the SSH account is therefore a trusted memory client. SSH key setup is handled normally by the machine's administrator. The installer does not copy private keys, create a root login or grant general sudo access.

See [the Hermes connection guide](../deploy/installer/clients/hermes/README.md) for connector 0.6.0. Its source and client installer are included, but the Debian server installer does not modify a user's workstation or Hermes settings. The client ZIP already contains a `cortex/` folder: extract into `~/.hermes/plugins/`, then run `python3 ~/.hermes/plugins/cortex/install.py --server USER@HOST --identity /path/to/key --known-hosts /path/to/known_hosts`. The client installer tests MCP recall before applying settings and backs up the previous connector and config. Existing `/opt/memory-cortex` deployments without the server wrapper require `--legacy`. Fully restart each client and verify a note saved by the other client; plugin-enabled status alone is insufficient.

## Validation status

Installer validation and bundle checks are described in `VALIDATION.md`. This release has **not been installed end-to-end on a fresh Debian machine**. Its application payload is based on the working Debian Cortex deployment; this is a first installer release for a controlled trial, rather than a claim of a fully tested clean install.

The application dependencies are version-pinned. Datastore images use explicit version tags for the initial download; setup records their resolved SHA-256 image digests for subsequent restarts. Debian packages come from the target machine's configured repositories; the embedding model is downloaded from Hugging Face. Installation therefore requires those sources to be available.

## Memory engines

Open Setup → Memory engines after installation. Choose local CPU embeddings or a remote embedding model, independently of local rules or a remote processing model. Ollama and OpenAI-compatible server APIs are supported. Enter the server URL, load or enter model names, test, then save. A model server must be reachable from the Debian machine. Chat models and embedding models serve different roles.

Embedding changes rebuild search into a separate collection before activating. The previous engine stays active if rebuilding fails. Original Markdown is unchanged; old indexes are retained. Processing supplies filing metadata rather than rewriting memory facts. Optional API keys stay in protected server-side configuration. Current settings are local MiniLM plus local rules until you choose remote engines.

## Recovery and memory review

Cortex now includes daily private application backups in addition to any VM backups. The timer runs at 02:15 UTC on a fresh install (with up to 10 minutes of jitter) and keeps the latest 14 archives. The existing cortex01 deployment uses 02:15 America/New_York. Writers pause briefly for a consistent backup. Check `systemctl list-timers cortex-backup.timer` for the next run. To disable or reschedule, use normal systemd timer administration.

Archives include the Markdown vault and Git, private provenance, forgotten notes, versions, engine preferences and provider keys, protected configuration, a PostgreSQL dump, a logical graph export and all vector collections. Archives are root-only under `/var/backups/cortex`; copy them to another machine/storage when needed. Proxmox Backup protects the VM independently. Application backups on the same VM alone do not protect against losing the VM/storage.

```
sudo cortex-backup create
sudo cortex-backup verify /var/backups/cortex/cortex-TIMESTAMP.tar.gz
sudo cortex-backup restore /path/to/archive.tar.gz --confirm-restore
```

Restore is for a matching Cortex installation. It first creates a safety archive and pauses writers. It restores application data into the existing five Cortex PostgreSQL tables, retaining database owners and grants. It also restores graph data, vectors, Markdown/Git and private metadata. This installation's vault path, service connection credentials and API keys are preserved; archived environment files are recovery references. Saved engine choices and provider keys are restored with metadata. If restoration fails, it attempts to roll back to the safety archive. If rollback also fails, writers remain stopped for administrator recovery. Verify readiness and a recall after restoring. Archive checksums verify integrity; they are not proof that a full restore rehearsal passed.

Overview shows active engines, bounded server connectivity checks, the latest index migration, recent active-model failures, backup status and timer state. Connectivity means the server/model is reachable and listed; use Setup's engine tests for an inference check. Diagnostics record timestamps/models/status only, never prompts or memory text.

Memories search combines keyword matches with semantic ranking. If embeddings are unavailable, keyword search remains available and the UI says so. Semantic similarity remains separate from combined ranking, and automatic note-discovery thresholds continue to use semantic similarity.

Memories → Duplicate review suggests possible overlap. Compare both notes, keep them separate, or edit the combined text and save a reviewed merge. The first note is retained; the second moves to Forgotten. Both current revisions are checked, so a concurrent edit cannot be silently overwritten. Dismissals expire when either note changes. Automatic merge is off by default. Check Enable automatic merge to merge all duplicate suggestions in background scans; uncheck it to return to manual review. The setting is saved server-side and survives page reloads and service restarts. Different bodies are combined without an LLM rewrite; identical bodies are retained once. Both originals remain recoverable through Version history and Forgotten. Automatic merges are identified in provenance.

Open a memory → Version history & undo to preview and restore a saved version. Earlier Git versions are included where available. Undo checks the current revision and refreshes search and graph; the replaced content remains recoverable. Restoring a pre-merge version does not automatically unforget the second note—restore that separately from Forgotten when wanted. Versions and trash may contain sensitive historical content and are private recovery data outside the searchable vault.

In Universe, select a connection line or a connection in a star's details. Cortex explains explicit wiki links, extracted relationships, mentions or inference rules, with supporting source memories and passages where recorded. Missing source evidence is stated explicitly. Confidence scores are extractor/inference scores, not verified probabilities.

Restart Hermes once after updating server application code so its persistent SSH MCP process loads hybrid retrieval and version capture. Engine choices themselves are read dynamically afterward.

## Universe view

Universe now includes a procedural nebula, layered stars that shift during panning, orbit halos, glowing links, hover highlighting and a smooth camera. Select a star to highlight its immediate connections; turn Focus connections off to keep every star bright. The scene shows the existing recorded graph and adds no inferred links of its own.

Immersive view expands the map. Jump to star remains available inside it, along with connection evidence and memory details. Escape exits immersive mode. Drag pans, scroll zooms around the pointer, +/− zoom, and 0 fits the map. Pause motion freezes ambient movement and camera transitions. Reduced-motion preferences are respected. Effects run locally in the browser without additional LLM calls.


## RAG and association discovery (installer 1.2.1)

Ask Cortex and RAG Sources are included, with CSV/TSV, XLS/XLSX, PDF, DOCX and text/code support. Configure a processing LLM in Setup for answers and discovery. Local/network/NFS paths are on the Cortex server; shares must already be mounted. SFTP host keys must be trusted. Refresh directory sources manually.

Associations compares Cortex vault memories in a bounded daily scan (six pairs by default). The installer enables cortex-associations.timer. Automatically accept checked associations is off by default. Select it on /associations to enable supported-only automatic links after quote validation, an additional model check and source revision checks. Tentative proposals remain for review. Undo link reverses accepted associations. Model checking is not independent verification.

Installer 1.2.1 validation: archive integrity, payload/source parity, shell syntax and installer/proxy regression tests. A new clean Debian VM installation and restore rehearsal have not been performed for this rebuild; prior validation notes are historical evidence for 1.1.1. This installer is for fresh hosts, not an in-place upgrade.

## Automatic duplicate merge

Open Memories → Duplicate review and use Enable automatic merge. This applies to all suggestions from the existing duplicate detector (identical bodies, wording overlap of at least 0.6, or vector similarity of at least 0.88), including existing suggestions. Similarity indicates overlap and does not guarantee that two memories describe the same fact; leave the setting off when manual review is preferred.

The watcher checks every 60 seconds while enabled, processing up to 50 suggestions from the bounded 500-memory snapshot. A note participates in at most one merge per scan. Remaining or newly found suggestions are handled by later scans. Scans may take longer while notes are being synchronized. The watcher service must be running. Dismissed pairs stay separate until either note changes; concurrent edits are skipped for reconsideration during a later scan.

Both notes’ text is preserved. The first note retains its identity and metadata; different bodies are appended under a Merged from heading, and the second note moves to Forgotten. The existing revision checks, version capture, index updates and rollback apply. Turn the setting off to stop subsequent merges; a merge already holding the mutation lock may finish before the off setting is saved. Turning off does not undo earlier merges.

To reverse a merge, restore the retained note’s pre-merge version from Version history & undo, then restore the second note from Forgotten. Turn automatic merge off before restoring to prevent a later scan merging the notes again. The private setting is stored in vault-metadata/duplicate-settings.json, included with metadata backups.

GET /ui/duplicates/settings reads {"automatic_merge": false}; POST to the same route saves a strict boolean automatic_merge field and requires the write API role. The LAN UI proxy permits the route only under its existing origin and request-header checks. Browser credentials remain server-side.

## Hermes connector installation (installer 1.3.0)

Connector 0.6.0 includes an installer and a read-only MCP recall check. It repairs the extra cortex/cortex directory layout, creates the real SSH command path, backs up the previous provider/config and applies local-memory injection settings only after recall succeeds. The fresh Debian installer runtime and artifact builder both use version 1.3.0. Client and package regression checks do not replace a fresh Debian installation and restore rehearsal.


## Release 1.3.0 — knowledge quality

Includes application 0.8.0a0, connector 0.6.0, revision-bound conflict review, graph-assisted recall, consistent connection evidence, human correction feedback, reviewed document-to-memory promotion, and repeatable evaluations. Open Fact review and Learning from the sidebar. Restart existing Hermes sessions after updating the server.

Retrieval omits empty Markdown sections and keeps shell comments/fenced code together. Rebuilding passages removes obsolete chunks even if a note's text revision is unchanged.

Fresh installations start with empty memory and private metadata. No personal notes, real evaluation questions, model credentials or source definitions are bundled. Configure your models and sources in Setup/RAG Sources. Real-world questions and feedback remain private to each installation. Document promotion requires review and never modifies original documents.

This is a fresh Debian 13 amd64 installer, not an in-place application upgrader. Archive checks, installer/proxy regressions and application acceptance checks are verified for this release; a fresh Debian VM installation and restore rehearsal have not been performed for 1.3.0.


## Release 1.3.1 — periodic RAG refresh

Application 0.8.1a0 adds source schedules (daily by default, configurable 1–168 hours), pause/resume controls, last/next attempt status, cross-process scan exclusion, hourly failure retry, and network-mount validation that preserves the last good index if a share disappears. The five-minute `cortex-rag-refresh.timer` and NFS client tools are installed on fresh Debian hosts. Per-installation network mounts and credentials remain administrator configuration. Connector 0.6.0 is unchanged. Existing source schedules default to enabled without changing source evidence revisions. A clean Debian installation/restore rehearsal has not been performed for this release.


## Release 1.3.2 — retrieval performance

Application 0.8.2a0 adds a bounded private passage cache with content-hash freshness checks, reused keyword postings with unchanged scoring, engine-bound reuse of exact Qdrant passage embeddings, and request-local promotion metadata. See docs/Performance.md. Connector 0.6.0 is unchanged. Existing source snapshots and evidence revisions need no migration; legacy vectors are re-embedded once before reuse. Application and installer/proxy tests, ranking/citation comparisons, package checksums and source parity are validated. A fresh-host install and full restore rehearsal are not repeated for this release.


## Release 1.3.3 — on-demand Universe exploration

Adds full-collection memory/entity search, additional star batches, paginated connection expansion, and starting a new map from a selected star. The read-only graph routes and graph-explore.js asset are included in the packaged dashboard proxy. Map views remain bounded to 1,000 stars. Application version remains 0.8.2a0 and Hermes connector remains 0.6.0. This is a fresh-host installer; a clean Debian installation and full restore rehearsal have not been repeated for this release.


## Release 1.3.4 — Universe motion and collection totals

Focused constellations keep revolving after the camera finishes zooming. Hovering, dragging, camera transitions, explicit pause and reduced-motion preferences still suspend rotation. The map displays “Showing N of X stars”, where X counts the full active memory and entity collection independently of page size and search. Filtered views update N; if the graph is unavailable the total is marked unavailable. Includes frontend motion/count regressions and full-collection count coverage. Application version remains 0.8.2a0 and Hermes connector remains 0.6.0. A fresh Debian installation and full restore rehearsal have not been repeated for this release.