Skip to main content
Visual Memory gives edge devices real-time recognition for both people and objects. Enroll a photo of a face or an item, and the live camera stream matches it against local vector embeddings with Moorcheh Edge - triggering actions like unlocking a gate or announcing where a product belongs on a shelf. Everything runs on a single board with no cloud dependency, so biometric and visual data stay private. Demo video: Visual Agentic Memory on Edge AI Devices Source repo: github.com/moorcheh-ai/ShelfIn
Install Docker on the board first. For general Edge install on Arduino-class hardware, see Arduino UNO Q. Visual Memory runs two Edge containers (faces + objects), not the default single :8080 store.

Overview

Visual Memory runs on Ventuno Q with Moorcheh Edge as the on-device match layer. A USB webcam watches the scene. The app does two jobs in parallel: When an item is known, the app builds a short spoken line:
  • Template mode (default) - fixed sentence from name + shelf
  • LLM mode (optional) - an external chat LLM (Ollama or OpenAI-compatible) rewrites the same facts already in memory into one natural sentence
Speech uses standalone Piper when installed under ~/piper/, with espeak as fallback. The browser never plays audio; the board speaker does. Everything that matters for matching stays on the board: models, vectors, and decisions. Spoken guidance does not use Moorcheh /answer or a third Edge RAG store. The optional LLM receives text facts only (already matched name / shelf / description) - never the camera image, and never an unknown detection. Powered by Moorcheh - PyPI moorcheh-edge, Docker moorcheh/moorcheh-edge.

Why Moorcheh Edge

Moorcheh Edge is built for on-device vector search. Visual Memory keeps two Edge stores on the same board: On edge hardware this matters:
  • Fast similarity search as galleries grow
  • Stable scores you can threshold for GRANT / DENY and known / unknown items
  • No cloud round-trip for identity or product match
  • Same Edge runtime pattern used across Moorcheh on-device projects
YuNet, SFace, YOLO, and ResNet stay in the Python app. Edge is the match layer. Spoken lines use a template or an external LLM; Piper / espeak is the voice layer.

Why edge access + shelf guidance?

  • Privacy - embeddings and decisions stay on the device
  • Reliability - matching does not depend on internet uptime
  • Latency - detect, embed, and search run on the board
  • Control - you decide thresholds and who / what is enrolled
  • Retail clarity - known items speak a shelf line; unknowns are never invented by the LLM
  • Simple ops - USB-C power, USB camera, browser UI after one-time setup

Architecture

End-to-end path from camera to UI and speaker:
Visual Memory system architecture

Visual Memory on Ventuno Q - faces and objects through dual Moorcheh Edge stores, then optional guidance and voice.

Diagrams (Figma): VENTUNO Face Access - System Architecture
Unknown objects get a red Unknown box only. They are not sent to the LLM.

Plain-language flow

  1. The USB camera sends frames into Visual Memory.
  2. The face path asks: “Do we know this person?” → grant or deny on the screen.
  3. The object path asks: “Is this an enrolled item?” → if yes, use its name, shelf, and description.
  4. If the item is known, build one short sentence (template or external LLM).
  5. Piper / espeak speaks that sentence on the board speaker.
  6. The browser shows the live stream, boxes, and status (Wi-Fi or HDMI).

Technical flow (faces)

  1. Frame (cadence every 3 frames, scale 0.35)
  2. YuNet detect → SFace embed (128-d)
  3. Search Moorcheh Edge faces
  4. Score ≥ FACE_MATCH_THRESHOLD (default 0.28) → ACCESS GRANTED + name

Technical flow (objects)

  1. Same camera frame pushed to a side thread (every 3 frames)
  2. YOLO proposes boxes (not names)
  3. ResNet embed (256-d) on each crop
  4. Search Moorcheh Edge objects (top 3, margin 0.03)
  5. Score ≥ OBJECT_MATCH_THRESHOLD (default 0.38) → known name + shelf + description
  6. Else → Unknown (draw only)

Technical flow (guidance + voice)

  1. Only known object facts (and optional person name) enter guidance
  2. GUIDANCE_MODE=template → fixed sentence from those facts
  3. GUIDANCE_MODE=llm → external chat LLM with the facts in the prompt; fallback to template if the LLM is down
  4. Standalone Piper (or espeak) speaks the line on the board speaker

What runs on Ventuno Q

Day-to-day: start faces Edge, start objects Edge, start the UI. Camera, thresholds, audio runtime, and Piper paths are set by start.sh defaults.

Features

Entrance / visitor
  • Live camera gate with ACCESS GRANTED / DENIED
  • Identity label and similarity score
  • Known item boxes + shelf line
  • Unknown object boxes without inventing names
  • Browser UI over Wi-Fi or HDMI
Staff
  • Multi-photo person onboarding
  • Item upload with name, shelf, description
  • Bulk CLI enroll for larger sets
Developers
  • Dual Moorcheh Edge stores
  • Optional external LLM guidance + Piper / espeak TTS
  • Scripts: start_faces_edge.sh, start_objects_edge.sh, start.sh, scripts/enroll_faces.py, scripts/enroll_objects.py

Hardware requirements

Software stack

Repo layout

How to: one-time setup

  1. Clone github.com/moorcheh-ai/ShelfIn
  2. Install Docker; add your user to the docker group
  3. Create a venv and install deps
  4. Download face models; place yolov8n.pt in the project root
  5. Optional: install Piper under ~/piper/piper/ (otherwise use espeak)
  6. Follow the repo README.md for any board-specific notes
Optional Piper paths (auto-detected by start.sh):
Otherwise install espeak-ng for spoken lines.

How to: every boot

start.sh already sets camera (opencv / index 0), object thresholds (0.38 / 0.55 / 0.03), XDG_RUNTIME_DIR, and Piper when installed. No exports required for the default demo.
Open: Enroll at least one person and one item before relying on live recognition.

How to: enroll faces and items

Staff enroll people and shelf items once. After that, live recognition can grant access and speak shelf lines.
Enroll faces and objects

Enroll faces and objects into the two Moorcheh Edge stores.

Enroll a person (UI)

  1. Open the Visual Memory UI
  2. Under Onboard a person, enter a display name
  3. Drop or choose several photos (JPG / PNG)
  4. Click Insert & authorize
  5. Vectors upload to Moorcheh Edge faces (:8083)

Enroll an item (UI)

  1. Under Add an item, enter name, shelf phrase, and optional description
  2. Drop or choose item photos
  3. Click Add item
  4. Vectors upload to Moorcheh Edge objects (:8081)

Bulk enroll (backend scripts)

For larger galleries, skip the UI and run scripts with Edge up:
Face and object images stay on the device (known_faces/ and known_objects/ are gitignored).

Enroll checklist

  1. Faces Edge up (start_faces_edge.sh)
  2. Objects Edge up (start_objects_edge.sh)
  3. Visual Memory UI running (start.sh) - or run the CLI enroll scripts with Edge up
  4. At least one person and one item enrolled
  5. Confirm both lists before relying on live recognition
Clear a store if dimensions conflict:

How to: live recognition

Live recognition

Live path: known face grants access; known item names its shelf and can be spoken.

  1. USB camera frame arrives
  2. Face path - YuNet → SFace → Edge faces → ACCESS GRANTED or ACCESS DENIED
  3. Object path - YOLO → ResNet → Edge objects → known item or Unknown
  4. If known → guidance sentence → Piper / espeak on the speaker
  5. UI shows boxes, scores, and gate status
Face grant / deny never depends on the LLM. Unknown objects never go to the LLM.

Defaults (no exports required)

Optional overrides

Only if you need them:
External LLM guidance (default is template - no LLM):
LiteRT YOLO (export on Mac/x86 only, not aarch64):

How matching works

Faces: frame → YuNet → SFace 128-d → Edge :8083 → GRANT / DENY Objects: frame → YOLO box → ResNet 256-d → Edge :8081 → known name or Unknown Guidance: known facts only → template or external LLM → Piper / espeak

Use cases

  • Door / lobby face access on Ventuno Q
  • Retail or warehouse shelf guidance for enrolled products
  • Privacy-first demos without cloud face APIs
  • Edge AI proof-of-concept before a fixed install

Next steps

Arduino UNO Q

Board Docker + moorcheh-edge basics

Upload vectors

Precomputed vector upload (same mode Visual Memory uses)

Retail Kiosk

Text + voice RAG kiosk on UNO Q

Source on GitHub

Source repo and README