Cybermem

Features

To install CyberMem on your local machine, run:

npx @cybermem/cli install

and follow the instructions in terminal.

Full Quick Start guide for every platform is available at cybermem.dev/#quickstart.

Why CyberMem?

Problem: Your AI tools (Claude, Cursor, Antigravity) don't share memory. Each session starts fresh.

Solution: CyberMem gives them a shared, persistent memory layer.

For Platform Engineers: CyberMem demonstrates advanced Infrastructure practices:

• IaC Automation: CLI generates Docker Compose, Ansible, or Helm depending on the target.
• Hybrid CI: Leverages a private Raspberry Pi runner to bypass QEMU overhead, achieving native ARM64 build speeds.
• Zero-Trust Access: Integrates Tailscale Funnel for secure, public access without port forwarding.

For MCP Engineers & Hiring Managers

CyberMem is a reference implementation of production MCP patterns:

🔐 Multi-tenant auth: Traefik ForwardAuth extracts MCP client identity into audit logs
📊 Zero-overhead observability: Vector pipeline converts logs → Prometheus metrics
🚀 Multi-platform IaC: CLI auto-generates Docker Compose / Ansible / Helm per target
☸️ Production deployment: Kubernetes with rolling updates, health checks, PVC
🔧 Hybrid CI/CD: Self-hosted ARM64 runner bypasses QEMU 10x slowdown

551+ commits • 25 releases • Full E2E testing

If you're building MCP infrastructure at companies like Descope, Anthropic, or similar — use this as a production pattern library.

📧 Open to MCP/Agentic Infrastructure roles: mikhailkogan17@gmail.com

Architecture Overview

---
config:
  theme: base
  wrappingWidth: 290
  fontSize: 11
---
graph TD
    subgraph CI["🚀 Hybrid CI/CD Pipeline"]
        GHA["**GitHub Actions**<br/>(Control Plane)"]
        Cloud["**GitHub Cloud**<br/>(AMD64 Builds)"]
        RPiR["**Self-Hosted RPi**<br/>(Native ARM64 Builds)"]
        
        GHA --> Cloud
        GHA --> RPiR
    end

    subgraph Gen["🏗️ IaC Engine"]
        CLI["**CLI**"]
        Templates["**Infrastructure Templates**"]
        CLI --> Templates

        Compose["**Docker Compose**<br/>(Local)"]
        Ansible["**Ansible**<br/>(IoT/Edge)"]
        Helm["**Helm Charts**<br/>(Cloud/K8s)"]

        Templates --> Compose
        Templates --> Ansible
        Templates --> Helm
    end

    subgraph Runtime["⚙️ CyberMem Runtime"]
        Traefik["**Traefik**<br/>(Reverse Proxy)"]
        LE["**Log Exporter**<br/>(Access Logs)"]
        DBE["**DB Exporter**<br/>(SQLite Metrics)"]
        Dash["**Dashboard**<br/>(Monitoring UI)"]
        OM["**Core API**<br/>(Memory Engine)"]
        DB["**SQLite / Postgres**<br/>(Persistence)"]

        Traefik -->|Logs| LE
        Traefik -->|API| OM
        OM --> DB
        LE --> DB
        DB --> DBE
        DBE --> Dash
    end

    Cloud -.-> Runtime
    RPiR -.-> Runtime
    Compose -.-> Traefik
    Ansible -.-> Traefik
    Helm -.-> Traefik

CLI Reference

CyberMem CLI provides a standardized set of commands for complete lifecycle management:

npx @cybermem/cli install    # Install/Initialize services (Mac/RPi/VPS)
npx @cybermem/cli uninstall  # Stop and teardown services
npx @cybermem/cli upgrade    # Pull latest images and update instance
npx @cybermem/cli backup     # Create a data backup (.tar.gz)
npx @cybermem/cli restore    # Restore from a backup file
npx @cybermem/cli reset      # Wipe database (Destructive!)
npx @cybermem/cli dashboard  # Open monitoring dashboard

[!IMPORTANT] Ansible-First Prod: For Raspberry Pi or remote servers, the CLI automatically leverages Ansible to ensure state-consistent, safe, and verifiable deployments.

Project Structure (Monorepo)

cybermem/
├── packages/
│   ├── cli/                  # Command-line tool (TypeScript)
│   │   ├── src/              # CLI logic
│   │   └── templates/        # ⭐ Infrastructure templates
│   ├── mcp/                  # MCP Server & Core Engine (TypeScript)
│   │   └── src/              # Tooling & Memory Logic
│   └── dashboard/            # Monitoring UI (Next.js)
├── docs/                     # Documentation sources
├── .github/
│   └── workflows/            # ⭐ CI/CD pipelines
└── README.md

Key innovation: packages/cli/templates/ contains the infrastructure-as-code templates. The CLI reads these, interpolates variables, and generates production configs.

Documentation

Full documentation available at docs.cybermem.dev:

🛠️ Architecture Narratives

Why Traefik for ForwardAuth?

Standard Node.js auth middlewares often fail on underpowered Edge devices (RPi) or cause high latency. CyberMem uses Traefik as a Reverse Proxy to handle authentication at the networking layer. This allows the Core API to remain "clean" and deterministic, while Traefik extracts identity headers (X-Client-Name) into audit logs before the request even hits the application.

Why Ansible for RPi but Helm for Cloud?

We follow the Infrastructure Appropriateness principle.

• RPi/Edge: Needs mutable state management and OS-level hardening (docker-compose, systemd). Ansible ensures idempotent state without the overhead of a control plane.
• Cloud/VPS: Scaling and high availability are paramount. Helm allows us to leverage Kubernetes native primitives (Ingress, PVC, HPA) for a truly elastic platform.

Verification & Proof-of-Work

We use tools/test-k8s.sh and the CyberMem Gatekeeper to guarantee that every release is stable. Below is the raw console verification of a production-grade deployment.

1. Kubernetes Resource Tree (Architecture Proof)

NAMESPACE: cybermem
NAME                                         READY   STATUS    RESTARTS   AGE
pod/cybermem-dashboard-6dd67f5586-djwwh      1/1     Running   0          2m
pod/cybermem-openmemory-65fdf6d85c-g628g     1/1     Running   0          2m

NAME                  TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
cybermem-lb           LoadBalancer   10.43.0.1      127.0.0.1     8626/TCP   2m
cybermem-dashboard    ClusterIP      10.43.79.62    <none>        3000/TCP   2m
cybermem-openmemory   ClusterIP      10.43.95.212   <none>        8080/TCP   2m

2. Ansible Idempotency (Operational Maturity)

# Proof of zero-drift state management on Raspberry Pi
ansible-playbook -i inventory/hosts.ini playbooks/deploy-cybermem.yml

PLAY [Deploy CyberMem to Raspberry Pi] **

TASK [Gathering Facts] **
ok: [raspberrypi.local]

TASK [cybermem : Pull latest images from GHCR] **
ok: [raspberrypi.local] => (changed=false)

TASK [cybermem : Start services] **
ok: [raspberrypi.local] => (changed=false)

PLAY RECAP **
raspberrypi.local   : ok=15   changed=0    unreachable=0    failed=0    skipped=0

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Created by Mikhail Kogan
📧 Open to MCP/Agentic Infrastructure roles: mikhailkogan17@gmail.com
🔗 LinkedIn • CV (PDF)