Memphis

English · Polski

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 usually 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, sensitive credentials protected locally, and no built-in telemetry or analytics.

Durable runtime actions are written to operator-owned chains. Secrets are encrypted at rest, and sensitive tools are guarded by explicit authorization tiers. Memphis is more than a chat interface: it is a sovereign cognitive runtime designed for operators who want to own their memory, configuration, and execution boundary.

Current version: v1.12.0 (matches package.json) | Status: operator-supervised runtime — native Rust cockpit, chain-backed memory, encrypted vault, local and cloud provider routing, MCP/HTTP/Telegram surfaces, Kartograf ONNX inference, and composable skills. See CHANGELOG.md for release details and docs/dev/v1.10.0-deferred-work.md for the previous release's explicit deferrals.

Public surface: memphis-v5.pl · start · docs · roadmap · llms.txt · agents.json

---

First time? Read ONBOARDING.md

The canonical quick pointer: install paths, daily-use runbook, and operator docs map. Skip to "Install" below if you already know what you want.

Install

Linux, macOS, or WSL2. Installs Node 22, Rust stable, Ollama, 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

Add --with-init to continue into the interactive first-run flow (operator passphrase, vault passphrase, recovery answers, and identity):

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

Then (or if you left --with-init off) walk the canonical first-run:

memphis init                    # passphrase, vault, identity, first chain writes
memphis provider add anthropic  # (optional) cloud provider — repeat for minimax/deepseek/glm
memphis service install && memphis service restart  # Linux / WSL systemd-user only; see macOS note below
memphis tui                     # open the native operator cockpit

memphis init also installs seven safe, typed scheduler jobs (health/SLO watch, scoped backup retention, read-only doctor diagnosis, daily/weekly reflection, attachment quarantine, and the 09:00 Europe/Warsaw operator briefing). They run inside Memphis—do not add a separate system crontab.

memphis schedule list
memphis schedule reconcile --dry-run

macOS operators: memphis service install wires a systemd-user unit, so the step above is a no-op on macOS. Either run the runtime in a terminal with npm run dev while you need it, or provision a launchd plist at ~/Library/LaunchAgents/chains.memphis.runtime.plist that execs the same command. The remaining steps (memphis init, memphis provider add …, memphis tui) work identically across Linux, macOS, and WSL.

If memphis: command not found after install: the post-install npm link step is path-scoped. Run hash -r to refresh the shell hash, or which memphis to confirm the binary location, then either add that directory to PATH or re-run npm link from the repo root.

That's it. You now have an operator-owned runtime with encrypted credentials, chain-backed memory, optional cloud providers, and local Ollama support. Build time depends heavily on the machine because the first install compiles the Rust workspace.

What you get:

• Encrypted vault — Argon2id + AES-256-GCM, separate operator and vault passphrases, plus recovery Q&A
• Provider cascade — the requested or configured default provider is tried first, followed by the configured cascade and an always-available local-fallback. The built-in cascade order is ollama → anthropic → minimax → local-fallback and can be overridden with MEMPHIS_PROVIDER_CASCADE; DeepSeek and GLM are also supported
• Chain-backed memory — 11 canonical chains plus 8 semantic case roles, with SHA-256-linked blocks (Ed25519 signing activates when RUST_CHAIN_REQUIRE_SIGNATURES=true)
• Native TUI cockpit (Rust) — chat, memory browser, session history, vault, cases, system health, all in one terminal
• Telegram-ready — memphis setup telegram or .env config for remote bot access
• MCP-ready — stdio + HTTP transport for MCP-compatible clients
• HTTP API — Fastify on :3000, bearer-token protected, /v1/chat/*, /v1/ops/status, /v1/vault/*, SSE session events
• Kartograf ONNX runtime — memphis kartograf … for embedding + zone routing; ~700 MB checkpoint, lazy-loaded
• Skills composition — memphis skills … for scaffold / validate / install skills without round-tripping through generic file-write tools

New to Memphis? Step-by-step walkthrough — English or Polish (12 steps with verification after each) assumes zero prior knowledge and explains what each command does and why.

Experienced operator? Jump straight to docs/operator/install.en.md or docs/operator/install.pl.md for the compact reference.

---

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. Local operation stays local. Data leaves the machine only through providers or integrations you explicitly configure and invoke.
• Chain-backed truth. Every journal entry, decision, reflection, and system event is written to append-only SHA-256 linked chains. No silent edits. No disappearing history. Ed25519 block signing is available behind an opt-in flag (RUST_CHAIN_REQUIRE_SIGNATURES=true) for environments that need cryptographic non-repudiation; the default is SHA-256 linkage only.
• Vault-sealed provider credentials. Provider keys and integration tokens belong in the AES-256-GCM + Argon2id vault. Bootstrap-level secrets such as MEMPHIS_API_TOKEN and MEMPHIS_VAULT_PEPPER remain in the permission-tightened local .env; neither location is committed.
• 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

The installer prepares local configuration and an operator-profile scaffold, but it does not initialize the vault or write the first identity/memory chains. First-run remains deliberate. 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

What you want	Command
First-run (passphrase + vault + identity)	memphis init
Health check	memphis health
Diagnose + auto-repair	memphis doctor --fix
Start / stop / restart daemon	memphis service {start,stop,restart}
Daemon status	memphis service status
Recent daemon logs	memphis service logs -n 100
Open native TUI console	memphis tui
List configured providers	memphis providers list
Inspect vault	memphis vault list
Add a vault secret	memphis vault add <key>
Memory write	happens automatically during memphis tui / memphis ask (agent calls memphis_journal tool)
Hybrid search (semantic + FTS5)	memphis search --query "<phrase>"
Agent self-modification log	memphis evolve log

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/operator/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

Capability	What It Means
Chain Memory	11 canonical append-only, SHA-256-linked chains: journal, decisions, reflections, cases, patterns, system, collective, proactive, insights, soul, and messages. Ed25519 signing is opt-in through RUST_CHAIN_REQUIRE_SIGNATURES=true. Session memory and conversation compaction are derived overlays, not separate sources of truth.
Encrypted Vault	AES-256-GCM + Argon2id protection for provider keys and integration credentials. Bootstrap secrets remain in a local permission-tightened .env; both stores are excluded from Git.
5 Cognitive Modes	A (Capture), B (Inference), C (Prediction), D (Collective), E (Meta-Reflection). The selected mode changes runtime dispatch and cognitive contribution.
Rust TUI	Native operator cockpit with live chat streaming, transcript scrollback, wrapped output, busy animation, token/context telemetry, and pressure visibility across Overview, Chat, Memory, Sessions, Vault, Cases, System.
MCP Server	Shared runtime tool lane with factory-backed tool registry, bounded concurrency for safe tools, and tier-based authorization (Tier 0/1/2).
Telegram Gateway	Bidirectional companion surface for operator commands and runtime events. Configure vault-backed credentials with memphis setup telegram; the native TUI remains the primary operator cockpit.
Self-Modification	Git snapshot + branch + test gate + approval. Tier 2 (vault passphrase) required. Memphis can improve itself — with your permission.
Provider Cascade	Ollama, Anthropic, MiniMax, DeepSeek, GLM, and local-fallback. The requested/default provider is attempted first; retryable failures walk the configured cascade and terminate at local-fallback.
Worker / Async Runtime	Local worker runner plus HTTP work-polling, signed worker session tokens, and scheduler/async chat dispatch without splitting runtime truth.
ISKRA / MEMORY / PULSE	Identity prompt, burn-after-action log, heartbeat monitor — the soul system. Memphis knows who it is, remembers what it did, and monitors its own health.

---

Architecture

Operator (you)
  |
  +-- CLI (memphis <cmd>)          -- broad operator and automation 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, SHA-256 linking, optional Ed25519 (RUST_CHAIN_REQUIRE_SIGNATURES=true)
  |     +-- memphis-vault          -- AES-GCM encryption, Argon2 KDF
  |     +-- memphis-embed          -- Embeddings pipeline
  |     +-- memphis-export         -- Chain export + migration utilities
  |     +-- memphis-paths          -- Cross-platform path resolution
  |     +-- 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 SHA-256 linked chains, source of truth (Ed25519 optional via RUST_CHAIN_REQUIRE_SIGNATURES)
        +-- data/memphis.db        -- SQLite indexes (derived, rebuildable)
        +-- ~/.memphis/vault-entries.json -- Encrypted vault entries (AES-256-GCM)

No telemetry or analytics. Memphis does not phone home. Local operation stays local; network traffic occurs only for providers and integrations the operator configures. SQLite indexes are derived from chains and can be rebuilt. The chains are the source of truth.

---

Authorization

Memphis assigns registered tools to tiers 0–2. A separate time-bounded tier-3 permission session can relax selected execution restrictions after operator-passphrase verification; tier 3 does not register a fourth class of tools.

Tier	Auth Required	What You Can Do
0	None	Journal, recall, health checks, case queries — read your own memory
1	API token	Vault secrets, config writes, provider changes — modify your runtime
2	Vault passphrase	Source modification, tool install, branch ops — change Memphis itself

---

CLI

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

# Memory
memphis search --query "<phrase>" # Hybrid semantic + FTS5 retrieval
memphis chain verify              # Chain integrity check
memphis reflect                   # Meta-cognitive reflection
# Cognitive mode A-E can be changed from the TUI, Telegram, HTTP, or MCP surfaces.
# Journal writes happen automatically during `memphis tui`/`memphis ask`
# (agent calls the `memphis_journal` tool — not a top-level CLI verb)

# Vault (see docs/dev/key-lifecycle.md for the full flow)
memphis secret add --key <key> --value <plaintext>  # Store encrypted secret (gated by passphrase)
memphis secret get --key <key>                       # Retrieve & decrypt (gated by passphrase)
memphis secret list                                  # List stored secret keys + metadata
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 providers list           # Show configured providers
memphis provider add <name>      # Add provider (key goes to vault)

# Telegram
memphis setup telegram --bot-token <token> --allowed-user-ids <csv>
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 schedule list            # Built-in jobs and their last/next run
memphis schedule reconcile --dry-run # Preview canonical scheduler migration
memphis evolve                   # Self-modification (tier 2)

---

Configuration

Memphis uses .env for non-secret configuration, vault references, and two bootstrap secrets generated locally (MEMPHIS_API_TOKEN and MEMPHIS_VAULT_PEPPER). Provider and integration credentials should be stored in the encrypted vault.

DEFAULT_PROVIDER=anthropic           # requested default; requires configured credentials
MEMPHIS_PROVIDER_CASCADE=ollama,anthropic,minimax,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 setup telegram --bot-token <token> --allowed-user-ids <csv>

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 suite
npm run test:rust          # Rust workspace suite
npm run -s cli -- doctor   # Deep health check

---

Troubleshooting

Problem	Fix
memphis not found	npm link from repo root, then hash -r
Rust build fails	sudo apt install build-essential pkg-config libssl-dev
Ollama not available	curl http://127.0.0.1:11434/api/tags — install Ollama if missing
Chain integrity error	memphis doctor --json — check chains section
Vault locked	Use an interactive vault/secret command; if the passphrase is lost, run memphis vault recovery-unlock

See Troubleshooting Guide for decision trees.

---

Documentation

Start here → Operator Handbook — single-page entry point covering Day 0 install through Day 90 DR drill.

Doc	Purpose
Operator Handbook	One-page operator workflow by time horizon
SLO Baseline	Latency / error budgets and breach policy
Key Lifecycle	Pepper provisioning, vault init, provider keys, rotation
Disaster Recovery	Backup / restore / cross-host vault recovery
Chain Integrity	chain verify, archive GC, snapshots
Cognitive Modes	A/B/C/D/E dispatch, frame pipeline
Config On The Fly	Hot / warm / cold field taxonomy, reload paths
Surface Parity	Capability matrix across TUI / Telegram / MCP / HTTP
Observability	Request-id, alert fan-out, Grafana dashboard
Voice	Telegram STT/TTS, /voice on|off, daily TTS quota
Cognitive Frames	Mode A frame buffer, post-turn capture, dispatch
Self-Update	memphis self-update check, /v1/ops/status.latestVersion
Self-Restart	Tier-3 /restart across Telegram / TUI / HTTP / MCP / CLI
Force Flags	MEMPHIS_VAULT_FORCE_REINIT + MEMPHIS_RESTART_ALLOW_SUICIDE bypass contracts
Clean Install	Canonical install path from source
Installation	Prerequisites, install, verify
User Guide	Complete operator manual
Troubleshooting	Debug, fix, recover
Architecture	System boundaries and layers
Rust Distribution	NAPI bridge: per-platform sub-packages + S9 migration plan
Project Status	Current state and maturity
Roadmap	Current roadmap and milestones
Upgrade Guide	Migration between versions
Release Process	GPG signing, secrets, key rotation, release smoke

Current planning lives in docs/ROADMAP-CURRENT.md. Historical planning snapshots are preserved under docs/archive/.

---

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 planned Lisp-like language for hardware control and inter-agent communication. Its integration path is documented on the long-term roadmap and is not part of the current Memphis workspace.
• 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 X.Y.Z-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 X.Y.Z

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

CI Preflight Gates

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