Celiums Memory

A complete cognitive memory engine. Apache-2.0. All of it.

Development branch notice: this branch is dev work for the Rust and Cloudflare migration. It is not production-ready and must not be used for production data, customer traffic, or public release artifacts. The stable user-facing line remains main until the production gates below are closed.

Celiums Memory is an engine, not an app — no UI, no dashboard to log into. It is the memory, journaling, ethics and knowledge substrate you embed inside other software: agents, assistants, tools, pipelines. It speaks MCP (Model Context Protocol) so any compatible client (Claude Code, Cursor, Continue, Cline, OpenCode, or your own) gets persistent memory, a first-person journal, an auditable ethics engine, and a per-user biological clock — without you building any of it.

Implementation status: the Rust workspace in rust/ is the canonical implementation. The Cloudflare Worker, Durable Object, R2 and Container runtime are the target deployment path and are still being validated on dev. See the ordered Rust roadmap, the execution ledger, and ADR-025.

It is open source under Apache-2.0 in full: no open-core split, no paid tier, no proprietary core held back. The Ethics Engine — every layer — is open and auditable. Its ethics_knowledge corpus is distributed separately as a v2.0.0 release asset (not in the git tree); the engine runs on Layers A+B without it, and Layer K (precedent) abstains cleanly when the corpus is absent.

A fuller statement of intent: MANIFESTO.md.

Target Architecture

MCP / HTTP client
    |
    v
Cloudflare Worker
    |  authentication, tenant resolution, edge limits
    v
Durable Object per tenant
    |  command journal, receipts, high-water mark, R2 pointer
    v
Disposable Cloudflare Container generation
    |  native Rust binary, one tenant filesystem
    v
Hyphae 0.2.1
    |  hash-chained log, verified snapshots, embedded indexes
    v
Celiums Memory Rust engine
    cognitive core + ethics + governance + recall + journal + graph

The Container filesystem is disposable. The Durable Object is the serialized control plane, and encrypted checkpoint artifacts are stored in R2. This is the architecture being built and tested; it is not an assertion that this branch is ready for production deployment.

The native Rust binary remains the local reference runtime. It supports MCP stdio, authenticated MCP Streamable HTTP, REST v1, OpenAPI, tenant-scoped actors, and 19 MCP tools. The Worker and Container layers must agree with that native contract before canary promotion.

cd rust
cargo build --release -p celiums-memory-cli
cargo run --release -p celiums-memory-cli -- mcp --data ../.celiums/memory

MCP client configuration:

{ "command": "celiums-memory", "args": ["mcp"] }

The target production request path is:

MCP client / HTTP caller
        │
         ▼
 Worker auth + tenant routing
          ▼
 Durable Object → Cloudflare Container → native Rust MCP/HTTP server
          ├─► Hyphae append-only durable engine
          ├─► encrypted R2 checkpoint generations
          └─► caller-provided or Workers AI embeddings

The pieces:

• Memory — remember / recall with hybrid retrieval (vector + full-text + affective/PAD resonance), importance scoring, consolidation, lifecycle decay, and circadian/interoceptive modulation.

• Journal — append-only, hash-chained, first-person agent journal: causal chains, arcs, introspection, dialogue, chain verification.

• Ethics Engine — a 4-layer evaluator (A deterministic lexicon · B probabilistic CVaR with a categorical CBRN hard-block · C philosophical scaffold · K precedent advisory). Fully open, corpus included — the component that makes moral calls is the one that least deserves to be hidden.

• Biological clock — per-user circadian rhythm modulates arousal and recall; the engine has a sense of time and state.

• Knowledge — forage does hybrid search over the skills/knowledge you bring (BYO; via the skills table). The large curated module corpus is a separate Celiums project — forage runs without it.

• Storage — Hyphae-backed native Rust durability inside the Container; the Durable Object is the Cloudflare control plane and recovery journal.

• Recovery — mutating requests carry X-Celiums-Operation-Id; the DO persists pending, forwards the original command, stores the terminal receipt, advances a contiguous high-water mark, and replays unresolved tail operations after a Container failure.

• Checkpoints — encrypted Hyphae backups are wrapped as versioned binary artifacts, uploaded to R2, referenced by a durable DO pointer, retained as recent generations, and restored only into a new verified tenant generation.

Full detail — tenant isolation, confirmation gates, ethics layers and observability — is in ARCHITECTURE.md.

Related MCP server: MCP AI Memory

Development Status

This section describes the work currently being integrated into dev. It is intentionally explicit so that development architecture is not mistaken for a shipped product contract.

Completed Foundation

• Rust cognitive core with importance, affect/PAD, limbic state, retention, circadian modulation, ethics Layers A/B/C/K, and deterministic recall.

• Hyphae-backed durable engine with exact Q15 retrieval, BM25F lexical search, typed abstentions, dimension guards, durable state, and verified recovery.

• Tenant, user, agent, project, conversation and session identity contracts.

• Idempotent ingestion, event ledgers, batch ingestion, provider enrichment boundaries, temporal claims, contradiction detection, entity graph, hierarchical consolidation, lifecycle maintenance, and time-travel recall.

• Policy-aware governance, disclosure controls, poisoning/PII/secret handling, append-only audit chains, deletion, export, migration planning, encrypted backups, and restore verification.

• Native Rust server with REST v1, MCP Streamable HTTP, OpenAPI, API-key auth, OIDC verifier boundary, RBAC, confirmation tokens, quotas, rate limits, request IDs, health, readiness and version endpoints.

P10 Cloudflare Migration

• Removed the legacy TypeScript memory runtime, shared TypeScript types, legacy schemas, SQL migration runner, Postgres/Qdrant/Valkey deployment paths, Docker Compose path, and Helm release path from this development line.

• Moved plugin and benchmark transport to the authenticated native Rust server.

• Added a Worker control plane with tenant-bound Container routing.

• Added a Durable Object command journal with transactional pending records, terminal receipts, idempotency conflicts, contiguous high-water marks, and pending-tail replay.

• Added binary-safe checkpoint transport so large encrypted artifacts are not converted to UTF-8 or stored as giant journal receipts.

• Added native checkpoint export/import routes and a versioned CELIUMSCP artifact over the existing encrypted Hyphae backup primitive.

• Added R2 checkpoint pointers, three-generation history, retention, pending binary objects, Queue delivery, and Durable Object alarm scheduling.

• Added native/Worker conformance tests for auth, tenant isolation, replay, checkpoint metadata, binary preservation, and idempotency.

What We Are Modeling

The migration is not only a language rewrite. It models a product-grade memory substrate with explicit boundaries:

• Physical tenant isolation: a tenant is resolved before storage is opened; request payloads never select a tenant directory.

• Durable command semantics: acknowledged writes have an operation identity, a receipt, a sequence, and a recovery story instead of relying on ephemeral process state.

• Disposable compute: Container generations can be destroyed and rebuilt from verified checkpoint plus journal replay without changing operation IDs.

• Evidence-preserving memory: raw events, claims, graph edges, summaries, policy traces, journal chains and audit records preserve provenance rather than collapsing everything into opaque vectors.

• Read-only recall: retrieval does not silently mutate memory or emotional state; feedback and maintenance are explicit operations.

• Governed disclosure: sensitive content, persistent instructions, secrets, operational intent and user-visible disclosure are separate decisions.

• Deterministic behavior: dimensions, filters, embedding identity, corruption, unsupported formats and degraded retrieval fail explicitly.

• Portable ownership: logical exports, encrypted backups, verified restore, hard delete and residue reports remain first-class capabilities.

• Provider neutrality: the engine does not own an LLM or embedding provider; production callers may supply Workers AI, bge-m3, another compatible model, or the deterministic local embedder for development.

• Operational quality: the intended product must expose health canaries, redacted telemetry, recovery drills, versioned artifacts, reproducible builds, conformance suites and clear rollback boundaries.

Not Ready For Production

This dev line must not be promoted until all of the following are green in a real Cloudflare environment:

• Worker authentication and tenant routing against production secrets.

• Durable Object serialization and journal durability under concurrent traffic.

• Container start, stop, destroy, restart and generation replacement behavior.

• R2 write, read, retention, corruption detection and encrypted restore.

• Queue delivery, retry, deduplication and pending-tail replay.

• RPO 0 for acknowledged writes and measured recovery objectives.

• Native versus Container conformance using the same fixtures and result schema.

• Recall health canary, tenant isolation canary and backup/restore canary.

• Crates.io publication and clean-consumer installation for the public Rust family.

• Production security review, release provenance, runbooks and disaster-recovery drill.

Until then, use main for the stable public line. Treat all dev APIs, artifacts, package metadata and Cloudflare configuration as subject to breaking change.

Quick start

Option A — Native Rust server

git clone https://github.com/terrizoaguimor/celiums-memory.git
cd celiums-memory
export CELIUMS_API_KEY_PEPPER=local-development-pepper-change-me
celiums-memory serve --data ~/.celiums/memory \
  --api-keys 'cmk_local:default:developer:developer:owner'
curl localhost:3210/healthz  # → live, once ready

The native MCP/HTTP server listens on :3210.

Option B — MCP stdio

git clone https://github.com/terrizoaguimor/celiums-memory.git
cd celiums-memory
celiums-memory mcp --data ~/.celiums/memory

The MCP stdio mode is local and requires no external services.

Connect an MCP client

Point any MCP client at the HTTP endpoint with the API key. Example for Claude Code / Cursor-style config:

{
  "mcpServers": {
    "celiums-memory": {
      "url": "http://localhost:3210/mcp",
      "headers": {
        "Authorization": "Bearer cmk_your_key_here",
        "x-celiums-tenant-id": "default"
      }
    }
  }
}

From then on the client can call remember, recall, journal_write, forage, ethics_trace, and the rest — and auto-bootstrap loads prior context into the first response automatically.

Configuration

Set via environment. The essentials:

Ethics knowledge corpus (Layer K — optional)

The Ethics Engine runs on Layers A + B with zero setup. Layer K (precedent advisory) consults an ethics_knowledge corpus that is not in the git tree — it ships as a v2.0.0 release asset (ethics_knowledge.jsonl, ~31 MB, embeddings precomputed). To enable Layer K, point OPENSEARCH_URL at your OpenSearch and load it:

OPENSEARCH_URL="https://user:pass@your-opensearch:25060" pnpm exec tsx scripts/load-ethics-knowledge.mjs

The loader downloads the release asset, verifies its SHA-256, creates the index with the exact mapping, and bulk-indexes it (idempotent — re-runnable; --force recreates, --dry-run validates without writing). Until then Layer K abstains cleanly; A + B are unaffected.

The MCP tool surface

Development

pnpm install
pnpm typecheck
cargo check --manifest-path rust/Cargo.toml --workspace

The deployable is the Rust celiums-memory-cli binary. The Cloudflare Worker under apps/cloudflare-worker authenticates requests and routes one Container per tenant.

Integrating

The engine is built to live inside your stack and is consumed over MCP or authenticated HTTP. The plugin and benchmark packages are transport adapters, not storage runtimes.

License & support

Apache-2.0 — every line of source is public, including the full Ethics Engine. Its ethics_knowledge corpus ships as a release asset (see Releases), not in the git tree. See LICENSE and TRADEMARKS.md.

If Celiums Memory is useful to you, you can sponsor its development. It is built — in the open, going its own way in peace — by Celiums Solutions LLC.