# Memory Cortex Server for Apple Silicon

Native server preview 0.2.3. macOS 14 or later, Apple Silicon only.

The app and installer use the same head-and-brain icon as the server manager. The build generates the .icns asset, embeds it in the app, and sets both the mounted-volume and DMG-file Finder icons.

The app bundles native arm64 Python, PostgreSQL 16, Qdrant 1.18.0, Neo4j Community 5.26.0, Java 21, Git 2.51.0, the Cortex application, and its standard local embedding model. It uses no Docker, virtual machine, Homebrew, system Python, or Rosetta on the destination Mac. Universal libraries in third-party runtimes include an arm64 slice.

## Use

Copy **Memory Cortex Server.app** to Applications and open it. Click **Start Server**. Once every service shows Running, click **Open Workspace** for Universe, Memories, Ask, and Setup. Local embeddings and rule-based filing work without a separate model server; Setup can connect to your chosen Ollama or compatible endpoint.

Closing the window leaves services running, with a head-and-brain icon in the menu bar. Its menu offers **Open Server Dashboard** and **Quit Server and All Services**. The dashboard action recreates its window after it has been closed. **Stop Server** or **Quit Memory Cortex** stops child services and databases. Closing the app does not delete data. Services run as the logged-in user, not root, and require the user session to remain running. This preview does not register an automatic login item or system daemon.

The local workspace is `http://127.0.0.1:58090`. Beneath it the control panel displays this Mac’s SSH address (`username@hostname.local`) and its active network IPv4 address when available. These update when the network changes. The address does not enable macOS Remote Login; enable it on the server before configuring an SSH client. Remote web access uses an SSH tunnel because the workspace remains bound to loopback. All listeners bind to loopback, with separate authenticated internal API/database endpoints. Ports: PostgreSQL 55432; Qdrant HTTP 56333 / gRPC 56334; Neo4j HTTP 57474 / Bolt 57687; API 58088; dashboard 58090. Occupied ports cause startup to fail rather than attaching to another server. LAN serving is not enabled in this preview. For agent access, **Copy MCP Command** supplies the local stdio command with no credentials in its command line. Keep the app running while using that command.

## Universal Mac client

The server console's **Clients…** button opens client enrollment. Start the server, enter a client name, a reachable hostname or IP, and SSH port (22 by default), then choose **Download Configured Client…**. The username is the macOS account running the server. Enable **System Settings → General → Sharing → Remote Login** for that account first. The app does not enable Remote Login, create OS accounts, open router ports, or change the Mac's login password. For the same Mac use `127.0.0.1`; for another machine use a reachable LAN/VPN address. Bonjour `.local` names generally work only on the same LAN.

The downloaded ZIP contains a signed **Memory Cortex Client.app** and **Connection.cortexclient**. Transfer it privately to the destination Mac, unzip it, and launch the app with the connection file beside it. If moving the app into Applications first, use **Import Connection…** to select the sibling file. The client is a universal arm64 + x86_64 binary for macOS 14 or later; it needs no Python, package manager, or installed SSH keys. The server itself remains Apple Silicon only.

Click **Connect & Verify**, then choose an agent and **Configure Selected Agent**. The client validates SSH and an actual MCP initialize/tools-list exchange before enabling configuration. Supported setup targets are ChatGPT Desktop / Codex (local stdio MCP), Claude Desktop, Claude Code, and Hermes CLI. **Other MCP agent** copies a JSON configuration for compatible local MCP clients. Missing CLIs produce an actionable message; existing user settings are preserved and backed up before changes. Restart the selected agent afterward. Hermes setup adds Cortex MCP tools; it does not replace Hermes's memory provider. Hosted ChatGPT and other cloud agents do not read local MCP configuration and require their own remote connector.

The app installs a persistent helper under `~/Library/Application Support/Memory Cortex Client/bin/CortexBridge`. Agents launch it on demand. The native client stays in the menu bar when its setup window is closed, using the head-and-brain icon. Its menu has exactly **Open Memory Cortex** and **Quit**. Open launches the server workspace in the default browser, starting at Universe; all workspace tools are available. Quit stops the local browser gateway and its SSH requests. Reopening the app from Finder opens its connection/setup window. Already-enrolled clients start hidden in the menu bar on subsequent launches; no automatic login item is installed. The helper uses the system SSH client, verifies a pinned Ed25519 server host key, and reads its private identity from the login Keychain. Private SSH identity files needed by OpenSSH exist only in private temporary directories during a connection and are removed on normal termination. An unlocked login Keychain is required; macOS may ask to authorize the app/helper after an update.

Each configured download contains a one-time bootstrap SSH key, expiring after 24 hours. It is exchanged for a new client-generated identity on first connection, then removed from the client Keychain. Server account passwords and Cortex database/API credentials are never included. The server adds a marked entry to the current account's `~/.ssh/authorized_keys`, preserving unrelated entries. `restrict` plus forced commands permit enrollment, Cortex MCP, and the fixed Cortex workspace endpoint. SSH shell access and SSH port forwarding remain disabled. The client web gateway binds only to an ephemeral loopback port, authenticates browser requests with a private HttpOnly/SameSite cookie, validates Host and Origin, and forwards bounded requests over SSH to the server workspace at 127.0.0.1:58090. API/database keys remain on the server. Other server ports and arbitrary URLs cannot be requested through this transport. The browser URL is session-specific and expires when the client quits; open the workspace from the menu-bar icon again after restarting. MCP tools carry the logged-in server account's Cortex capabilities, including memory writes. Give downloads only to trusted agent owners. The ZIP is confidential until enrolled, revoked, or expired.

The Clients panel lists pending, active, expired, and revoked clients. **Revoke** removes that client's marked SSH key and closes active MCP and web sessions within a few seconds. Stopping/quitting Cortex closes managed client sessions and prevents new ones. Expired bootstrap entries are refused by the forced enrollment command and may be removed with Revoke. Server SSH host-key changes require a new profile; the client will not silently trust a changed host. Revoke unused clients before deleting or retiring the server data folder, which contains the access dispatcher.

The generic client ZIP is also built separately, without any connection credential. Build it with `scripts/macos/build_client.py --output /absolute/output --cache /absolute/cache --icon /absolute/MemoryCortex.icns`. Personalized downloads use the identical signed app with a separate connection file, preserving its code signature. Client creation is available only in the native server console; no unauthenticated credential-download endpoint is exposed by the workspace.

Sources for agent setup: [OpenAI local MCP documentation](https://learn.chatgpt.com/docs/extend/mcp), [Claude Desktop MCP setup](https://modelcontextprotocol.io/docs/develop/connect-local-servers), and [Claude Code MCP](https://code.claude.com/docs/en/mcp).

## Data and backups

Data is stored in `~/Library/Application Support/Memory Cortex/`. Vault, metadata, database directories, credentials, logs, and model cache are separate from the .app bundle. The folder is private (0700); generated credentials and configuration files are 0600. Secrets are stored in private server configuration because the background services need them; they are not included in the distributed app.

Use **Data Folder** or **Logs** to inspect local files. Stop the server, then choose **Back Up…** to create a consistent private `.tar.gz` archive containing databases, vault/history, metadata, and credentials. Treat backups as confidential. Logs and model cache are excluded. The backup command refuses a running instance and a destination inside the data directory.

To restore a cold backup: quit the app; retain a copy of the current data folder; extract the archive into a separate private folder; inspect the `Memory Cortex` directory; restore it to its original data-folder path; then launch the same compatible app version. Configuration includes absolute paths. Do not restore into a different path or upgrade database major versions without an explicit migration. A graphical restore/migration assistant is not included in this preview.

This starts a separate local server with an empty vault. Existing Debian-server memories stay on that server. Migrating the existing server is separate work, requiring a verified backup and compatible database restore.

## Uninstall

**Uninstall Memory Cortex.app** is included beside the server app in the DMG and beside the client app in client ZIP downloads. It is also bundled inside both apps: choose **Uninstall…** in the server control window or client setup window. The in-app action copies the uninstaller to a private temporary folder so it can remove its parent app safely; that temporary copy removes itself when it exits. The independent uninstaller is universal (Apple Silicon + Intel), macOS 14+, and needs no Python or package manager on the destination Mac. It can also remove older previews that use these application/data locations.

Select Server, Client, or both. **Keep server data** and **Keep saved connection profiles and Keychain keys** are checked by default. Review the displayed app and data paths before confirming. Installed app copies in other locations can be selected with **Choose App…**; a copy on a read-only installer volume is refused. Nothing is changed by opening the uninstaller or cancelling its confirmation.

Server removal asks the server app to quit and waits for its databases/services. A verified orphan supervisor can receive a graceful stop request; remaining services are identified by both bundled runtime and the matching Cortex data location. Another instance's processes are left alone. The uninstaller stops rather than force-killing a database if shutdown cannot be verified. It removes only the selected server's marked SSH client entries and marks its access records revoked, preserving unrelated authorized keys and a private SSH-file backup. macOS Remote Login and user accounts are not changed. Reinstalling a server whose clients were revoked requires issuing new client downloads.

Client removal quits the menu-bar app, removes the Cortex-owned entries from ChatGPT Desktop/Codex, Claude Desktop, Claude Code and Hermes configuration, and stops/removes the installed bridge helpers. Agent settings are backed up before editing; other connections/settings remain. Unrecognized or malformed config formats are preserved for manual review. Restart agents after uninstalling to discard cached MCP settings. Connections configured manually in other applications must be removed in those applications.

If saved client connections are removed, the uninstaller first tries to revoke each identity on its server through the trusted installed bridge, then removes only Cortex identity/bootstrap entries from its Keychain service. Remote revocation requires client 0.1.2 and server 0.2.2 or later and a reachable SSH server; failed/unsupported revocations are reported so they can be completed in that server's Clients panel. The local removal can still finish when a remote server is unavailable. Keychain removal is explicitly called out in the confirmation and cannot be undone by restoring files from Trash.

Apps, bundled runtimes, selected data folders and helpers move to **Trash**, rather than being permanently erased. External backups and downloaded installers/connection ZIPs are kept. Keeping server/client data leaves it in Application Support for a later reinstall. The uninstaller removes only the selected installed app copies; additional copies can be selected in another run.

## Build

Build on Apple Silicon with Xcode (Swift compiler and macOS SDK), Python 3.12+, make, curl and hdiutil. Only build-time tools are required; they are not destination requirements. Use Xcode's developer directory if Command Line Tools lack the SwiftUI macro plugin:

```sh
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
python3 scripts/macos/fetch_runtime.py /absolute/build-cache
python3 scripts/macos/build_app.py --cache /absolute/build-cache --output-dir /absolute/output
```

The builder fetches the standard model into `build-cache/embedding-model`, using the pinned revision in `deploy/macos/model-lock.json`, and records its source in `cortex-model-source.json`. The model is included so first use needs no network. All runtime download URLs and SHA-256 values are pinned in `deploy/macos/runtime-lock.json`. Python application dependencies are pinned in requirements.txt; the built bundle records the full installed set in python-packages.txt. The builder preserves third-party runtime licenses and produces THIRD-PARTY-NOTICES.txt.

Rebuilds may reuse an assembled runtime with `--skip-pip`; use a fresh output folder or omit that flag when requirements change. Public source and server payload come from Git-tracked files; stage new files before building. Never point the builder at a production data folder.

Create a verified disk image with `python3 scripts/macos/package_dmg.py --folder /absolute/output --output /absolute/Memory-Cortex-Server-arm64.dmg` after adding a quick-start guide alongside the app. Quit the preview app before packaging.

The default build output is ad-hoc signed for local development. Public server 0.2.3, client 0.1.3 and uninstaller 0.1.1 packages use Developer ID signing, Apple notarization and stapled tickets. See [the distribution signing workflow](macOS-Signing.md). Validate the final downloadable archives and their checksums; no Gatekeeper bypass is part of the app. These remain previews, and a clean-machine/older-macOS hardware matrix has not been completed.

## Validation

Supervisor tests exercise private credentials, persistent configuration, occupied-port refusal, backup locking and confidentiality, and protection of another running instance's status. The end-to-end smoke test starts all native services in an isolated workspace data directory and checks readiness, saving/retrieving a memory, search, the graph, persistence across restart, and graceful shutdown. Test results are recorded with the delivered build; a successful build alone does not establish these results.

Client validation includes access-control unit tests, isolated agent-config merge/backup checks, and a temporary localhost SSH daemon test covering enrollment, replay/expiry, strict server pinning, MCP handshake, shell/port-forward refusal, revocation, shutdown, and an independent helper reading its identity from Keychain. No production SSH entries or agent settings are changed by these tests. Intel slices are cross-compiled and inspected; Intel hardware execution is a separate validation step.

The menu-bar workspace feature requires native server 0.2.1 and client 0.1.1 or later. Existing enrolled profiles remain usable after upgrading both applications. Reconnect once if macOS asks to authorize the updated helper in Keychain.

Uninstaller validation uses disposable homes/apps/agent configs, a dedicated temporary Keychain service, and fake server processes. It covers keep-data and remove-data selections, unrelated settings/SSH preservation, symlink refusal, own-process verification, orphan shutdown, leaving another instance running, review cancellation, and the native completion screen. Production apps, data and credentials are never used as uninstall fixtures.