Operations

Cerememory is distributed as source. There are no published container images, package archives, or deployment templates — every operator builds the cerememory binary themselves and runs it as a long-lived process. This page covers what operating that binary in practice looks like.

Single-Server Topology

┌─────────────────┐     ┌─────────────────┐
│  Claude Code    │     │  Codex CLI      │
│  (cerememory    │     │  (cerememory    │
│   mcp --server  │     │   mcp --server  │
│   -url ...)     │     │   -url ...)     │
└────────┬────────┘     └────────┬────────┘
         │                       │
         │ stdio (MCP)           │ stdio (MCP)
         │                       │
         └───────────┬───────────┘
                     │
                     │ HTTP/CMP
                     ▼
        ┌─────────────────────────┐
        │  cerememory serve       │
        │  127.0.0.1:8420         │
        │  owns redb + Tantivy    │
        └─────────────────────────┘

Every MCP client launches its own thin cerememory mcp --server-url … proxy. The proxy speaks MCP to the client and HTTP/CMP to the shared server.

Build the Binary

git clone https://github.com/co-r-e/cerememory.git
cd cerememory
cargo build -p cerememory-cli --release

The binary lands at target/release/cerememory. Place it on PATH or reference it by absolute path from your service manager and MCP client configs.

Run as a Service

macOS (launchd)

~/Library/LaunchAgents/com.cerememory.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.cerememory</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/cerememory</string>
    <string>serve</string>
    <string>--config</string>
    <string>/usr/local/etc/cerememory/cerememory.toml</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/usr/local/var/log/cerememory.log</string>
  <key>StandardErrorPath</key>
  <string>/usr/local/var/log/cerememory.err</string>
</dict>
</plist>

Load with launchctl load ~/Library/LaunchAgents/com.cerememory.plist.

Linux (systemd)

/etc/systemd/system/cerememory.service:

[Unit]
Description=Cerememory living memory database
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
ExecStart=/usr/local/bin/cerememory serve --config /etc/cerememory/cerememory.toml
Restart=on-failure
RestartSec=5
User=cerememory
Group=cerememory
StateDirectory=cerememory
ReadWritePaths=/var/lib/cerememory
ProtectSystem=strict
ProtectHome=true
NoNewPrivileges=true
PrivateTmp=true
 
[Install]
WantedBy=multi-user.target

Enable with systemctl enable --now cerememory.

Health Probes

Both /health and /readiness bypass authentication and rate limiting so they remain reachable when auth is enabled.

Metrics

Prometheus metrics live at GET /metrics. They are disabled by default — enable with http.metrics_enabled = true. When auth is enabled, /metrics requires the same Bearer token as the rest of the API.

Headline series:

• cerememory_http_requests_total{method,path,status} — total HTTP requests
• cerememory_http_request_duration_seconds{method,path,status} — request latency histogram
• cerememory_encode_total{store} — encode operations per target store
• cerememory_encode_duration_seconds{store} — encode latency histogram per store
• cerememory_recall_total — recall operations
• cerememory_recall_duration_seconds — recall latency histogram
• cerememory_decay_panics_total — recovered panics inside the background decay loop (alert when non-zero)

At-Rest Encryption

Set security.store_encryption_passphrase (or CEREMEMORY_SECURITY__STORE_ENCRYPTION_PASSPHRASE) to encrypt newly written redb store records. Existing plaintext records remain readable so the engine keeps serving traffic during migration.

To rewrite legacy plaintext payloads with the configured passphrase, run a one-shot migration against a quiesced data directory:

cerememory migrate-store-encryption --confirm

The command reports per-store totals (raw_journal, episodic, semantic, procedural, emotional, vector_index) and exits non-zero on failure. Always take a CMA archive backup beforehand.

When store encryption is enabled, persistent search indexes default to in-memory only. Set security.persist_search_indexes = true only if it is acceptable for derived text to appear on disk.

Audit Log

A tamper-evident JSONL audit log is enabled by default at <data_dir>/audit.jsonl. Each entry chains to its predecessor via a SHA-256 hash, so any reorder, rewrite, or deletion breaks the chain. Verify integrity periodically:

cerememory audit-verify

Pass --path /path/to/audit.jsonl if the audit log was relocated via security.audit_log_path. Disable the log entirely with security.audit_log_enabled = false (not recommended).

Entry schema

Every line is one JSON object:

{
  "version": 1,
  "sequence": 42,
  "timestamp": "2026-04-28T03:14:15Z",
  "operation": "encode.store",
  "record_ids": ["01916e3a-..."],
  "store_types": ["episodic"],
  "summary": { /* operation-specific JSON, never raw memory content */ },
  "prev_hash": "<sha256 hex of the previous entry>",
  "entry_hash": "<sha256 hex over (version, sequence, timestamp, operation, record_ids, store_types, summary, prev_hash)>"
}

The first entry uses an all-zero genesis prev_hash. cerememory audit-verify recomputes each entry_hash and rejects any blank line, sequence gap, or chain break.

Backups and Portability

CMA archives are the portability format. Export periodically and store the archive somewhere durable:

cerememory export \
  --output /var/backups/cerememory/$(date +%F).cma \
  --include-raw-journal \
  --encrypt \
  --encryption-key-stdin

Use --encryption-key-stdin so the passphrase never appears in ps output or shell history. Restore with cerememory import and the corresponding --decryption-key-stdin.

Scaling Notes

Cerememory uses an embedded database (redb), which has direct implications for scaling:

• No horizontal scaling. Each data_dir is owned by exactly one process. Two replicas pointing at the same directory will deadlock on file locks.
• Vertical scaling works well. The decay engine uses rayon for parallel computation across all CPU cores; the HTTP layer is async via Tokio.
• No read replicas. For redundancy, take regular CMA archive exports and replicate the encrypted archives to durable storage.

For exposing Cerememory to a network beyond loopback, set http.bind_address = "0.0.0.0", enable auth, and front the server with a TLS-terminating reverse proxy (nginx, caddy, traefik). gRPC supports native TLS via grpc.tls_cert_path / grpc.tls_key_path.

Next Steps