Skip to content

About

Face memory demo for enrollment, verification, and assistant access using Streamlit, InsightFace, SQLite, and DashScope.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Human Face Agent Memory

Human Face Agent Memory is a Streamlit demo app for enrolling face identities, verifying access with face recognition, and opening a personal assistant after a user is recognized.

The app is designed as a public demo, not as production-grade physical or account access control. Face verification can be spoofed by photos, videos, or lookalikes unless a proper liveness layer is added.

Features

  • Face enrollment with profile metadata and face embeddings stored in SQLite.
  • Access verification against registered face memories.
  • Verified-user assistant chat powered by DashScope/VLM.
  • My Memory view for verified users to review and delete their saved memory.
  • Automatic production cleanup for user information after 12 hours based on created_at.
  • DashScope token usage tracking that is preserved when user information is deleted.
  • Public-demo rate limits for register, verify, and chat operations.
  • Production default avoids retaining raw reference images.
  • Streamlit toolbar deploy button hidden through .streamlit/config.toml.

Privacy And Security Notes

This project handles biometric data. Treat the SQLite database and environment files as sensitive.

  • In production mode, the app stores profile information and face embeddings temporarily.
  • In production mode, raw reference images are not retained by default.
  • Access images are processed for the current verification attempt and are not stored.
  • Submitted images may be sent to DashScope/VLM when vision validation is enabled.
  • User information is deleted automatically after 12 hours in production, and users are also prompted to delete My Memory manually after verification.
  • The app has no login system. The public demo flow relies on face verification and session state.
  • This app should not be used as real access-control security without stronger controls such as liveness detection, authentication, monitoring, and hardened infrastructure.

Requirements

  • Python 3.12 recommended.
  • A DashScope API key when REQUIRE_VISION_VALIDATION=true or chat is used.
  • CPU mode works by default. GPU can be configured through INSIGHTFACE_DEVICE.

Install dependencies from:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Configuration

Create a local .env file:

cp .env.example .env

Then set at least:

DASHSCOPE_API_KEY=your_api_key_here

Common environment variables:

Variable Default Description
APP_ENV dev Use dev for local development or prod for public-demo behavior.
DASHSCOPE_API_KEY empty DashScope API key used for VLM validation and chat.
DASHSCOPE_HTTP_BASE_URL https://dashscope-intl.aliyuncs.com/api/v1 in .env.example Optional DashScope HTTP base URL. Must use HTTPS.
MODEL_ID qwen3-vl-235b-a22b-thinking DashScope model ID.
DB_FILE face_memory.db SQLite database path.
INSIGHTFACE_DEVICE cpu Use cpu, gpu, gpu:0, cuda, or cuda:0.
REQUIRE_VISION_VALIDATION true Enables DashScope/VLM validation for enrollment and access.
FR_THRESHOLD 0.5 Face recognition similarity threshold.
DEFAULT_TOLERANCE 0.7 Default combined score tolerance for registered users.
DASHSCOPE_TOKEN_LIMIT 1000000 Global lifetime token limit tracked in SQLite.
STORE_REFERENCE_IMAGE false in prod, true in dev Controls whether raw reference images are retained.

.env, Streamlit secrets, SQLite database files, temp files, and caches are ignored by git.

Run The App

Development mode:

APP_ENV=dev .venv/bin/streamlit run app.py

Production-style public demo mode:

APP_ENV=prod DB_FILE=tmp/public_demo.db .venv/bin/streamlit run app.py --server.headless true

After Streamlit starts, open the local URL printed in the terminal, usually:

http://localhost:8501

Cleanup

The app enforces 12-hour user information cleanup in production mode. You can also run the cleanup CLI manually or through cron:

.venv/bin/python cleanup_user_info.py --retention-hours 12

Dry run:

.venv/bin/python cleanup_user_info.py --retention-hours 12 --dry-run

Example cron entry that runs every 12 hours:

0 */12 * * * cd /path/to/hface-memory && .venv/bin/python cleanup_user_info.py --retention-hours 12 >> cleanup.log 2>&1

Cleanup deletes rows from face_users only. DashScope token summary and token event tables remain intact.

Tests

Run the full test suite:

PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m unittest discover -s tests -v

The current tests cover runtime configuration, public UI copy, privacy cleanup, token usage preservation, production reference-image minimization, public rate limiting, and secret/debug regression checks.

Project Structure

app.py                  Streamlit UI and public-demo behavior
face_memory.py          Face memory system, SQLite storage, DashScope integration
schemas.py              Pydantic models for users and operation results
cleanup_user_info.py    CLI for scheduled user information cleanup
requirements.txt        Python dependencies
tests/                  Unit tests
.streamlit/config.toml  Streamlit client configuration

Public Demo Checklist

Before exposing the app publicly:

  • Set APP_ENV=prod.
  • Set DASHSCOPE_API_KEY through environment variables or Streamlit secrets.
  • Use a private database path with restricted file permissions.
  • Keep STORE_REFERENCE_IMAGE=false unless you explicitly need raw reference image retention.
  • Keep the cleanup command scheduled as a backup even though app-level cleanup runs in production.
  • Monitor DashScope token usage and public request volume.
  • Present the app as a demo only, not as real security infrastructure.

About

Face memory demo for enrollment, verification, and assistant access using Streamlit, InsightFace, SQLite, and DashScope.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages