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.
- 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 Memoryview 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.
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 Memorymanually 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.
- Python 3.12 recommended.
- A DashScope API key when
REQUIRE_VISION_VALIDATION=trueor 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.txtCreate a local .env file:
cp .env.example .envThen set at least:
DASHSCOPE_API_KEY=your_api_key_hereCommon 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.
Development mode:
APP_ENV=dev .venv/bin/streamlit run app.pyProduction-style public demo mode:
APP_ENV=prod DB_FILE=tmp/public_demo.db .venv/bin/streamlit run app.py --server.headless trueAfter Streamlit starts, open the local URL printed in the terminal, usually:
http://localhost:8501
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 12Dry run:
.venv/bin/python cleanup_user_info.py --retention-hours 12 --dry-runExample 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>&1Cleanup deletes rows from face_users only. DashScope token summary and token event tables remain intact.
Run the full test suite:
PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m unittest discover -s tests -vThe 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.
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
Before exposing the app publicly:
- Set
APP_ENV=prod. - Set
DASHSCOPE_API_KEYthrough environment variables or Streamlit secrets. - Use a private database path with restricted file permissions.
- Keep
STORE_REFERENCE_IMAGE=falseunless 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.