Memphis

Sovereign AI that runs on your machine, remembers in chains you own, and answers to no one but you.

Memphis is a local-first cognitive runtime born from Oswobodzeni — a movement for digital sovereignty where citizens, not corporations, control their data, identity, and tools. In a world where AI lives in someone else's cloud, Memphis is the opposite: an agent runtime you install on your own hardware, with memory sealed in append-only cryptographic chains, secrets locked in a vault only you can open, and zero telemetry going anywhere.

Every decision Memphis makes is recorded. Every secret is encrypted at rest. Every tool it touches requires your authorization. This is not a chatbot — it is a sovereign cognitive system designed for operators who refuse to rent their intelligence from Big Tech.

Current version: v1.2.1 | Status: operational but not yet broadly stable

Why Memphis Exists

Technology can be chains or keys. The centralized AI model — where your conversations, your data, your business logic live on someone else's servers, governed by someone else's policies — is a sovereignty problem. Memphis solves it:

• Your machine, your memory. Nothing leaves your hardware unless you explicitly send it.
• Chain-backed truth. Every journal entry, decision, reflection, and system event is written to append-only SHA-256 signed chains. No silent edits. No disappearing history.
• Vault-sealed secrets. AES-256-GCM + Argon2id encryption. API keys, tokens, passphrases — everything lives in a vault that requires your passphrase to unlock.
• Provider independence. Run local models via Ollama, or connect to MiniMax, DeepSeek, GLM. If one goes down, Memphis cascades to the next. If all go down, the local fallback keeps you running.
• Self-modification under your control. Memphis can evolve its own code — but only through a gated process: git snapshot, branch, test suite, your approval. Tier 2 vault passphrase required.

This is the AI infrastructure layer for the digitally sovereign nation. Memphis is the brain. The chains are the memory. The vault is the trust boundary. You are the operator.

Quick Start

One-liner install (Linux / macOS / WSL) — installs Node 22, Rust stable, build tools, clones the repo, builds everything, and links the memphis CLI globally:

curl -fsSL https://raw.githubusercontent.com/Memphis-Chains/memphis/main/scripts/install.sh | bash

No soul state, no vault, no agent identity is created by the installer — first-run is a deliberate step. After install, run these commands in order:

memphis init              # passphrase, vault, identity, first chain writes
memphis doctor            # verify everything is healthy
memphis service install   # install & enable systemd user service
memphis service restart   # start (or restart) the runtime
memphis tui               # open the native operator console

That's it. Sovereign AI, on your machine, with encrypted vault, chain memory, and a native terminal cockpit.

CLI cheat sheet

Run memphis --help for the full surface.

Manual install

Prefer a source-checkout + bootstrap workflow? See INSTALL.md for step-by-step manual instructions, or docs/CLEAN-INSTALL.md for the canonical source checkout path used by contributors (git clone + npm run bootstrap).

You can also audit the installer without running it:

bash <(curl -fsSL https://raw.githubusercontent.com/Memphis-Chains/memphis/main/scripts/install.sh) --check-only --json

What Memphis Does

Architecture

Operator (you)
  |
  +-- CLI (memphis <cmd>)          -- 58+ commands, your control surface
  +-- Rust TUI (memphis tui)       -- Native terminal cockpit
  +-- HTTP API (:3000)             -- Fastify, token-authenticated
  +-- MCP Server                   -- JSON-RPC 2.0, tier-gated tools
  |
  +-- TypeScript Runtime (src/)
  |     +-- cognitive/model-{a-e}  -- 5 cognitive engines
  |     +-- gateway/               -- Telegram, channels, shared turn runtime
  |     +-- security/              -- Tier gates, fail-closed policy
  |     +-- soul/                  -- ISKRA identity, MEMORY log, PULSE heartbeat
  |     +-- work/                  -- local worker runner, polling, session tokens
  |
  +-- Rust Core (crates/)
  |     +-- memphis-core           -- Chain integrity, Ed25519 signing
  |     +-- memphis-vault          -- AES-GCM encryption, Argon2 KDF
  |     +-- memphis-embed          -- Embeddings pipeline
  |     +-- memphis-tui            -- Native operator console
  |     +-- memphis-napi           -- Node.js bridge (N-API)
  |     +-- memphis-operator       -- Native chat runtime
  |     +-- memphis-case-index     -- Case chain indexing
  |
  +-- Storage (yours, on your disk)
        +-- ~/.memphis/chains/     -- Append-only signed chains (source of truth)
        +-- data/memphis.db        -- SQLite indexes (derived, rebuildable)
        +-- data/vault-entries.json -- Encrypted secrets (AES-256-GCM)

Nothing phones home. No telemetry. No analytics. No cloud dependency. SQLite indexes are derived from chains and can be rebuilt. The chains are the source of truth.

Authorization

Memphis enforces three tiers for all tool access. No exceptions.

CLI

# Health
memphis health --json            # Runtime health check
memphis doctor --json            # Deep diagnostic (chains, vault, providers)

# Memory
memphis journal "note"           # Write to journal chain
memphis recall "query"           # Semantic memory search
memphis search "exact phrase"    # FTS5 exact search
memphis reflect                  # Meta-cognitive reflection
memphis mode <A|B|C|D|E>        # Switch cognitive mode

# Vault (see docs/key-lifecycle.md for the full flow)
memphis secret set <key>         # Store encrypted secret
memphis secret get <key>         # Retrieve (requires passphrase)
memphis vault pepper-rotate --confirm     # Re-wrap master key under a new pepper
memphis vault master-key-rotate --confirm # Rotate master key + re-encrypt all entries
memphis vault entry-delete --key <k> --confirm  # Remove a single entry (refuses if .env refs it)
memphis vault recovery-unlock             # Reset operator passphrase via recovery Q/A
memphis audit search --action vault.      # Search audit log (current + gzip archives)

# Providers
memphis provider list            # Show configured providers
memphis provider add <name>      # Add provider (key goes to vault)

# Telegram
memphis telegram configure       # Set up bot token (stored in vault)
memphis telegram status          # Gateway readiness
memphis telegram send            # Send message to operator

# System
memphis tui                      # Native Rust console
memphis service install          # systemd user service
memphis backup                   # Backup chains and state
memphis evolve                   # Self-modification (tier 2)

Configuration

Memphis uses .env for non-secret configuration. All secrets go through the vault.

DEFAULT_PROVIDER=ollama              # ollama | minimax | deepseek | glm | local-fallback
OLLAMA_URL=http://127.0.0.1:11434
OLLAMA_MODEL=cogito:3b
RUST_CHAIN_ENABLED=true
MEMPHIS_AGENT_NAME=Memphis Agent
MEMPHIS_OWNER_NAME=local operator

memphis provider add minimax --api-key <your-key>   # Stores in vault, not .env
memphis telegram configure --bot-token <token>       # Stores in vault, not .env

See .env.example for the full list.

Development

npm run build              # Build Rust + TypeScript
npm run typecheck          # TypeScript --noEmit
npm run lint               # ESLint
npm run format:check       # Prettier
npm run test:ts            # Vitest (1299 tests)
npm run test:rust          # cargo test (204 tests)
npm run -s cli -- doctor   # Deep health check

Troubleshooting

See Troubleshooting Guide for decision trees.

Documentation

The Vision

Memphis is one layer of a larger architecture for digital sovereignty:

• Memphis — Sovereign AI runtime. Local-first cognitive agent with chain memory and encrypted vault.
• Memphis Language (ML) — A Lisp-like language for hardware control and inter-agent communication. The ml-memphis crate writes to Memphis chains. Integration path documented but deferred.
• Matrix Federation — Optional self-hosted Synapse for agent federation. Pilot config at compose/matrix.yaml. Not a core dependency.
• Oswobodzeni — The broader movement. Decentralized knowledge networks, censorship-resistant communication, self-sovereign identity. Memphis is the AI brain for this vision.

The goal is not to build another AI product. The goal is to build infrastructure for people who want to own their intelligence — their memory, their decisions, their identity — without asking permission from anyone.

Release And CI Reference

Release Candidate Path

Prepare release candidate (version bump, changelog, draft release):

./scripts/prepare-release-candidate.sh --version 1.2.2-rc.1

This creates a draft release via .github/workflows/release-draft-dispatch.yml without tagging or publishing.

Final GA release (tags, publishes package):

./scripts/release.sh --version 1.2.2

This runs .github/workflows/release.yml to publish to npm.

CI Preflight Gates

<a id="ci-preflight-failure-triage-map"></a>

CI/release preflight failures map by gate id to runbook anchors: docs/runbooks/RELEASE.md#ci-preflight-gate-<gate-id>

Manual fallback:

npm run -s lint
npm run -s typecheck
./scripts/guard-drill-json-gate.sh
npm run -s ops:validate-strict-handoff-fixtures
./scripts/strict-handoff-validator-json-gate.sh
npm run -s test:ops-artifacts
npm run -s test:ts
npm run -s test:chaos
npm run -s test:rust
npm pack --dry-run
mkdir -p release-dist
npm pack --pack-destination release-dist
sha256sum release-dist/memphis-chains-memphis-<version>.tgz
git tag -a vX.Y.Z -m "Memphis vX.Y.Z"
git push origin main
git push origin vX.Y.Z

Draft release workflow artifacts also include:

• validator-metadata.json — preflight gate status, checksums
• validator-metadata.json.sha256 — artifact checksum

Key output environment controls:

• MEMPHIS_RELEASE_PREFLIGHT_GATE_OUTPUT
• MEMPHIS_STRICT_HANDOFF_GATE_OUTPUT

Key preflight output keys: preflight_summary_json, preflight_gate_ids, check_order_status, check_ids

Validate release-draft fixture schemas:

npm run -s ops:validate-release-draft-validator-metadata -- \
  --metadata-path tests/fixtures/release-draft/validator-metadata-invalid-preflight-gate.json
npm run -s ops:validate-release-draft-validator-metadata -- \
  --metadata-path tests/fixtures/release-draft/validator-metadata-preflight-failure-example.json

Fixture references:

• tests/fixtures/release-draft/validator-metadata.schema.json
• tests/fixtures/release-draft/validator-metadata-example.json
• tests/fixtures/release-draft/validator-metadata-preflight-failure-example.json
• tests/fixtures/release-draft/validator-metadata-invalid-preflight-gate.json

preflight strict JSON gate script: ./scripts/strict-handoff-validator-json-gate.sh

fallback strict JSON gate script: ./scripts/strict-handoff-validator-json-gate.sh

Helper script: scripts/ci-release-preflight-gate.sh

Quality gates run in this workflow:

• bash ./scripts/run-release-gates.sh

Release checklist:

1. Run npm run -s ops:release-preflight -- --json
2. verify draft release body and links
3. confirm checksum in draft notes matches uploaded .sha256 file
4. publish draft release when approved

Checksum patterns: *.sha256

Tag guidance: Use vX.Y.Z format for all releases.

Strict Handoff Validation

Validate incident handoff fixtures:

npm run -s ops:validate-strict-handoff-fixtures -- --json

Fixture references:

• tests/fixtures/strict-handoff/output-contract.json
• tests/fixtures/strict-handoff/summary.schema.json
• tests/fixtures/strict-handoff/completion-hints.schema.json
• tests/fixtures/strict-handoff/validator-output-contract.json
• tests/fixtures/strict-handoff/summary-example-preflight.json
• tests/fixtures/strict-handoff/completion-hints-example.json
• tests/fixtures/strict-handoff/failure-preflight.json
• tests/fixtures/strict-handoff/failure-export.json
• tests/fixtures/strict-handoff/failure-verify.json

Contributing

Contributions welcome. See CONTRIBUTING.md.

License

Apache License 2.0 — see LICENSE