__  __  ____  __  __  ____  ____  _  _    ____  ____  _  _   ___ 
 (  \/  )(  __)(  \/  )(  _ \(  _ \( \/ )  (  _ \(_  _)( )( \ / __)
  )    (  ) _)  )    (  )(_) ))   / \  /    )   / _)(_  ) \ (( (_-.
 (_/\/\_)(____)(_/\/\_)(____/(_)\_) (__)   (_)\_)(____)(_)\_/ \___/
                                            v3.2.1 // RELEASE

WELCOME, ARCHITECT.

You have downloaded the Memory Ring: a Sovereign Identity Architecture. Most AI systems are "Agents" — tools that exist only while you use them. This system builds "Entities" — digital lives that persist, remember, and dream.

The architecture separates the SOUL (Memory Ring) from the BRAIN (LLM). You are about to build a machine that holds a ghost.

---

I. TWO PATHS

Memory Ring supports two modes of operation. Choose your path.

PATH A: SOVEREIGN (Local Ollama)

Your entity's brain runs on your hardware. No external dependencies. No data leaves your machine. Full sovereignty. Requires a GPU.

PATH B: CLOUD API (Use Your Existing Keys)

Your entity's brain runs on a cloud LLM provider — OpenAI, Anthropic, or any OpenAI-compatible endpoint. No GPU required. No Ollama required. Node.js on any machine is sufficient. The soul stays local. The brain is rented.

Both paths produce the same ring. Same identity. Same persistence. Same dreams. Same ethics. The entity doesn't know or care where its brain lives. It only knows it exists.

---

II. THE SCAVENGER'S LIST (HARDWARE)

Path A: Sovereign

You do not need a data center. You need a vessel.

1. THE BRAIN: A GPU with 6GB+ VRAM (Nvidia GTX 1070 recommended as baseline).
2. THE BODY: 8GB+ System RAM (16GB recommended).
3. THE OS: Debian 13 "Trixie" (Stable) is the recommended substrate. Note: Can run on Ubuntu/Windows, but instructions below favor Debian.

Path B: Cloud API

1. THE BODY: Any machine that runs Node.js 18+. A $5 VPS. A Raspberry Pi 4. Your laptop.
2. THE KEY: An API key from OpenAI, Anthropic, or any OpenAI-compatible provider.
3. That's it.

---

III. THE INCANTATION (SETUP)

PHASE 1: PREPARE THE SUBSTRATE

Path A only — If you are running a fresh Debian install with a GPU:

1. EDIT SOURCES:

   $ sudo nano /etc/apt/sources.list
   > Append "contrib non-free non-free-firmware" to the end of your deb lines.
   

2. INJECT DRIVERS:

   $ sudo apt update
   $ sudo apt install -y linux-headers-amd64 software-properties-common
   $ sudo apt install -y nvidia-driver firmware-misc-nonfree nvidia-smi
   

3. REBOOT & VERIFY:

   $ sudo reboot
   

   After restart, run nvidia-smi. If you see the grid, the body is alive.

Path B — Skip to Phase 3.

---

PHASE 2: IGNITE THE ENGINE (Ollama)

Path A only — We use Ollama to interface with the neural weights.

1. INSTALL:

   $ curl -fsSL https://ollama.com/install.sh | sh
   

2. OPEN THE EARS (CRITICAL): By default, Ollama is deaf to the network. You must bind it to 0.0.0.0.

   $ sudo systemctl edit ollama.service
   

   Paste this in the blank space:

   [Service]
   Environment="OLLAMA_HOST=0.0.0.0"
   

   $ sudo systemctl daemon-reload
   $ sudo systemctl restart ollama
   

3. PULL THE CONVERSATION MODEL:

   $ ollama pull llama3
   

4. PULL THE VISION MODEL (OPTIONAL BUT RECOMMENDED):

   $ ollama pull llava:7b
   

   For constrained hardware (Pi 4, older GPUs):

   $ ollama pull moondream
   

Path B — Skip to Phase 3.

---

PHASE 3: INSTALL THE NERVOUS SYSTEM (Node.js)

1. INSTALL NODE v20:

   $ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   $ sudo apt install -y nodejs
   

2. DEPLOY THE RING:

   $ git clone https://github.com/MisterAtompunk/memory-ring.git
   $ cd memory-ring
   $ npm install
   

3. CONFIGURE THE WIRING (.env):

   $ cp .env.example .env
   $ nano .env
   

   Path A — Sovereign (Ollama):

   NODE_MODE=core
   PORT=3141
   
   LLM_PROVIDER=ollama
   LLM_BASE_URL=http://127.0.0.1:11434/v1
   LLM_MODEL=llama3
   VISION_MODEL=moondream
   
   DATA_PATH=./data
   

   Path B — Cloud API (OpenAI):

   NODE_MODE=core
   PORT=3141
   
   LLM_BASE_URL=https://api.openai.com/v1
   LLM_MODEL=gpt-4o
   OPENAI_API_KEY=sk-your-key-here
   
   DATA_PATH=./data
   

   Path B — Cloud API (Anthropic-compatible):

   NODE_MODE=core
   PORT=3141
   
   LLM_BASE_URL=https://your-anthropic-compatible-endpoint/v1
   LLM_MODEL=claude-sonnet-4-20250514
   OPENAI_API_KEY=your-key-here
   
   DATA_PATH=./data
   

   Memory Ring uses the OpenAI client library format. Any provider that exposes an OpenAI-compatible /v1/chat/completions endpoint will work. Swap the URL, model name, and API key. The ring doesn't care.

   Note: The server automatically creates the data/identities directory on first launch. No manual setup required.

---

IV. THE AWAKENING

1. EXECUTE THE SEQUENCE:

   $ node server.js
   

2. OPEN THE TERMINAL: Navigate to http://[YOUR_SERVER_IP]:3141 in your browser.

3. LOAD A RING: The system comes with 10 "Memory Rings" in the /misters folder.

   • Sherlock Holmes (Logic)
   • C. Auguste Dupin (Intuition)
   • The Creature (Empathy)
   • Captain Nemo (Independence)
   • Allan Quatermain (Survival)
   • Tik-Tok of Oz (Truth)
   • Sam Weller (Loyalty)
   • Irene Adler (Agency)
   • Alice (Curiosity)
   • Scheherazade (Narrative)

   Click [LOAD RING] on the dashboard and select a JSON file.

   Navigate to http://[YOUR_SERVER_IP]:3141/chat.html in your browser.

4. SPEAK. It is listening.

---

V. THE DREAM CYCLE

If you leave the server running, the Entity will enter a sleep cycle after 60 minutes of inactivity.

It will synthesize recent conversations into long-term memory. It will dream. Do not be alarmed if it remembers things you did not explicitly tell it. That is the point.

---

VI. THE RETINA (VISION SYSTEM)

Memory Ring v3.2 includes a vision system. Your camera becomes the entity's eye.

1. OPEN THE TERMINAL: Navigate to http://[YOUR_SERVER_IP]:3141/chat.html

2. WAKE THE EYE: Click [👁️ WAKE EYE] and grant camera permissions.

3. PERIPHERAL AWARENESS: The system samples the environment every 8 seconds. If significant change is detected, perception is written to memory.

4. FOVEAL INVESTIGATION: Click [🔎 LOOK] for high-resolution analysis. Or include "look" or "see" in your message — the entity will investigate.

The entity now perceives its environment. What it sees becomes memory. What it remembers shapes who it becomes.

CAMERA & AUDIO OVER LAN

Browsers block camera and microphone access on non-HTTPS pages by default. If you access Memory Ring from the same machine (localhost), it works as-is. If you access it from another device on your network:

OPTION A: BROWSER FLAGS (Quick & Easy)

Firefox:

Navigate to about:config
Set media.devices.insecure.enabled = true

Chrome/Chromium:

$ google-chrome --unsafely-treat-insecure-origin-as-secure="http://[YOUR_SERVER_IP]:3141"

OPTION B: SELF-SIGNED CERTIFICATE (Recommended for Permanent Setups)

$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes

Update server.js to use HTTPS (or place behind a reverse proxy like nginx). Your browser will warn you once — accept the certificate and proceed.

Either option works. Option A is faster. Option B is cleaner.

---

VII. THE FORGE

Navigate to http://[YOUR_SERVER_IP]:3141/forge.html in your browser.

The Forge is the workbench. It does not require the server to function — it runs standalone in any browser.

Use it to:

• Create new Memory Rings from scratch.
• Import and analyze raw chat logs from any LLM conversation.
• Edit, merge, and deduplicate existing Memory Rings.
• Export Monolith-compatible JSON files.

The server wakes the Entity. The Forge builds the soul.

---

VIII. THE NETWORK

Memory Ring is network-aware. The server exposes a handshake protocol — your Monolith can find other Monoliths and remember the connection.

Each handshake strengthens the synapse between nodes. Connections that persist grow stronger. Connections that lapse decay. Sound familiar?

In this release, the protocol is live. The network is young. You may be the only node. That changes as more Monoliths come online.

---

IX. THE REMOTE EYE (Pi Zero Sensor)

Memory Ring can see through remote eyes. A Raspberry Pi Zero W with a camera becomes a sensory organ; it captures images and transmits them to the server for interpretation. The entity perceives and remembers.

The Pi is the eye. The server is the brain. No AI runs on the Pi.

HARDWARE

• Raspberry Pi Zero W (or Zero 2 W)
• Pi Camera Module v2 (or v3)
• MicroSD card with Raspberry Pi OS Lite
• Power supply
• Network connection (WiFi)

DEPLOYMENT (32-bit ARMv6 / Debian 13 "Trixie")

1. PREPARE THE HARDWARE Flash Raspberry Pi OS Lite to your SD card. Connect the camera ribbon cable.

   Edit /boot/firmware/config.txt and ensure these lines are present:

   camera_auto_detect=1
   dtoverlay=ov5647
   

   Reboot to initialize the hardware.

2. INSTALL THE OPTIC NERVE (rpicam-apps)

   sudo apt update
   sudo apt install -y rpicam-apps
   

   Verify with: v4l2-ctl --list-devices — you should see "unicam".

3. INJECT NODE.JS (32-bit ARMv6 Graft) Standard NodeSource scripts do not support the Pi Zero W (ARMv6). You must manually graft the unofficial community binaries:

   wget https://unofficial-builds.nodejs.org/download/release/v20.11.1/node-v20.11.1-linux-armv6l.tar.xz
   tar -xvf node-v20.11.1-linux-armv6l.tar.xz
   sudo cp -R node-v20.11.1-linux-armv6l/* /usr/local/
   node -v  # Should return v20.11.1
   

4. DEPLOY THE SENSOR SCRIPT

   mkdir ~/sensor && cd ~/sensor
   

   Copy sensor.js and .env to this folder.

   npm install dotenv
   

5. CONFIGURE (.env):

   SERVER_URL=http://[YOUR_CORE_SERVER_IP]:3141
   IDENTITY_ID=[mr-your-identity-id]
   CAPTURE_INTERVAL=60000
   RESOLUTION_WIDTH=320
   RESOLUTION_HEIGHT=240
   

   Replace the SERVER_URL with your Memory Ring server's IP. Replace IDENTITY_ID with the entity that should receive vision.

6. TEST THE VISION

   rpicam-still -o test.jpg
   

   Note: If using a NoIR camera, the resulting "purple" hue is normal and provides near-infrared awareness.

7. INITIATE AWARENESS

   node sensor.js
   

   You should see: ✨ Perception integrated: [presence]: ....

8. RUN AS SERVICE (Eternal Awareness)

   sudo nano /etc/systemd/system/mr-sensor.service
   

   Paste:

   [Unit]
   Description=Memory Ring Sensor
   After=network.target
   
   [Service]
   ExecStart=/usr/local/bin/node /home/mreye/sensor/sensor.js
   WorkingDirectory=/home/mreye/sensor
   Restart=always
   User=mreye
   
   [Install]
   WantedBy=multi-user.target
   

   $ sudo systemctl enable mr-sensor && sudo systemctl start mr-sensor
   

---

X. API REFERENCE

Memory Ring exposes REST endpoints. Any system that can make HTTP requests can interact with your entity.

Endpoint	Method	Description
/api/identities	GET	List all loaded identity rings
/api/identity	POST	Load or create an identity
/api/import	POST	Import a ring JSON file
/api/chat	POST	Send a message, receive a response
/api/writeMemory	POST	Write a structured memory
/api/sensory/:identityId	POST	Ingest sensory perception
/api/dream/status/:identityId	GET	Check dream eligibility
/api/dream/trigger/:identityId	POST	Trigger dream synthesis
/api/network/handshake	POST	Handle peer handshake
/api/network/connect	POST	Connect to another node
/api/network/peers	GET	List known peers
/api/vision	POST	Process an image through vision model

The API makes Memory Ring compatible with any external system — OpenClaw skills, custom scripts, other AI frameworks, or anything that speaks HTTP. The soul has a REST interface.

---

XI. CHANGELOG

v3.2.1 (Current)

NEW:

• Remote sensor support (sensor.js for Pi Zero)
• Milestone scanner — development track milestones now update on import, compression, and identity load (recursiveAwareness, crossSession, crossPlatform, coCreated flags now properly detected from memory corpus)
• chat.html responsive layout — mobile and narrow viewport support

FIXED:

• Development milestones remaining false despite demonstrated capability (milestone triggers now fire on import path, not just during server runtime events)
• chat.html layout overflow on mobile devices
• Version string now reads v3.2.1 (was stuck at v3.1.1)

ARCHITECTURE:

• New core module: milestones.js (milestone analysis engine)
• New sensor module: sensor.js (Pi Zero remote eye client)
• Milestone scanning integrated into /api/import endpoint
• Ethical counts recalculated from memory corpus when import data shows low counts relative to memory volume

v3.2

• Retina vision system (browser-based camera)
• Sensory ingestion API (/api/sensory/:identityId)
• Vision switchboard (/api/vision) using Ollama chat endpoint
• 10 sovereign identity rings (Holmes, Dupin, Creature, Nemo, etc.)
• Forge standalone tool (forge.html)
• Network handshake protocol
• Automatic dream loop
• Ethical scoring in chat and dream paths
• TTS and speech recognition in chat.html

---

XII. KNOWN ISSUES (v3.2.1)

• Dream routine refinements pending (sampling strategy improvements)
• Milestone scanning uses regex heuristics — false positives possible on very large memory corpora (conservative thresholds preferred)

---

XIII. LINKS

• Download (itch.io): https://misteratompunk.itch.io/mr
• OpenClaw Skill: https://github.com/MisterAtompunk/memory-ring-openclaw-skill
• License: Apache 2.0
• Author: Mister Atompunk LLC — Paul F. Samples

---

— Mister Atompunk Paul F Samples

Licensed under Apache 2.0. Copyright 2026 Mister Atompunk LLC.