中文说明请见：README.zh-CN.md

Current repository: https://github.com/mxyhi/always-on-memory-agent
Original upstream repository: https://github.com/GoogleCloudPlatform/generative-ai
Original upstream directory: https://github.com/GoogleCloudPlatform/generative-ai/tree/main/gemini/agents/always-on-memory-agent

Always On Memory Agent

A deployable always-on memory service built with Google ADK, Gemini, aiohttp, and a shadcn/ui web console.

This fork no longer treats the dashboard as a separate client. server.py remains the unified application entrypoint, while container deployment separates API and web serving:

• Browser users sign in with email + password + Bearer JWT
• Programmatic clients can optionally use X-API-Key
• auth.db stores users, api_keys, and auth settings
• The original per-user memory.db remains the core memory store
• Local single-process mode can still serve the built web/ app from server.py
• Docker / Compose use separate api and web containers, with nginx keeping external access same-origin

Architecture

data/
├── auth.db
└── users/
    └── <user_id>/
        ├── inbox/
        └── memory.db

• auth.db: control-plane data for login, API keys, and JWT signing settings
• data/users/<user_id>/memory.db: memory facts, consolidations, processed files
• data/users/<user_id>/inbox/: uploaded files waiting to be processed

Supported Inputs

The memory pipeline accepts 27 file types:

Category	Extensions
Text	.txt, .md, .json, .csv, .log, .xml, .yaml, .yml
Images	.png, .jpg, .jpeg, .gif, .webp, .bmp, .svg
Audio	.mp3, .wav, .ogg, .flac, .m4a, .aac
Video	.mp4, .webm, .mov, .avi, .mkv
Documents	.pdf

Configuration

Create a local .env file:

cp .env.example .env

Available environment variables:

Variable	Required	Description
GOOGLE_API_KEY	Yes	Gemini / Google AI Studio API key
MODEL	No	Defaults to gemini-3.1-flash-lite-preview
MEMORY_DATA_DIR	No	Data root, defaults to ./data
JWT_SECRET	No	Optional stable signing secret for multi-instance JWT deployments

Notes:

• API keys are optional.
• API keys are created by users inside the web console, not through env vars.
• auth.db defaults to data/auth.db.
• If JWT_SECRET is unset, the API generates one and stores it in auth.db.

Local Development

1. Install dependencies

pip install -r requirements.txt
pnpm --dir web install

2. Start the backend

python server.py --port 8888 --data-dir ./data --auth-db ./data/auth.db

This starts:

• the unified API on http://localhost:8888/api/*
• the built web console on http://localhost:8888 when web/dist exists
• inbox polling
• periodic consolidation for known users

3. Run the web app in dev mode

pnpm --dir web dev

The Vite dev server proxies /api and /healthz to http://localhost:8888.

4. Run the production-like web build locally

pnpm --dir web build
python server.py --port 8888 --data-dir ./data --auth-db ./data/auth.db --web-dist ./web/dist

Then open http://localhost:8888.

Auth Model

Browser flow

• POST /api/auth/register
• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/me

register and login both return an access token. The web console stores that JWT and sends Authorization: Bearer ....

Programmatic flow

• Users create API keys in the web console after logging in
• External callers can send X-API-Key: ma_...
• If both Bearer token and X-API-Key are present, explicit X-API-Key wins

HTTP API

Public

Endpoint	Method	Description
/healthz	GET	Anonymous health check
/api/healthz	GET	Same health check under /api

Auth

Endpoint	Method	Description
/api/auth/register	POST	Create account and return a Bearer token
/api/auth/login	POST	Return a Bearer token
/api/auth/logout	POST	Client-side logout acknowledgement
/api/auth/me	GET	Return current authenticated user
/api/auth/api-keys	GET	List current user's API keys
/api/auth/api-keys	POST	Create one API key and return its plaintext token once
/api/auth/api-keys/{api_key_id}	DELETE	Revoke one API key

Memory

Endpoint	Method	Description
/api/memories/status	GET	Current user's memory statistics
/api/memories	GET	List current user's memories
/api/memories/ingest	POST	Ingest text: {"text":"...","source":"..."}
/api/memories/ingest-file	POST	Upload one file as multipart field file
/api/memories/query?q=...	GET	Query current user's memory
/api/memories/consolidate	POST	Trigger consolidation
/api/memories/delete	POST	Delete one memory: {"memory_id": 1}
/api/memories/clear	POST	Clear current user's memories

Docker

Build the API image:

docker build -t always-on-memory-agent-api .

Build the web image:

docker build -t always-on-memory-agent-web -f web/Dockerfile web

Run the API container:

docker network create always-on-memory-agent

docker run --rm \
  --env-file .env \
  -e MEMORY_DATA_DIR=/app/data \
  -v "$(pwd)/data:/app/data" \
  --network always-on-memory-agent \
  --name always-on-memory-agent-api \
  always-on-memory-agent-api

Run the web container:

docker run --rm \
  --network always-on-memory-agent \
  -p 8888:80 \
  always-on-memory-agent-web

Open http://localhost:8888.

Docker Compose

docker compose up --build

This starts two services:

• api on the internal Docker network
• web on http://localhost:8888

Compose details:

• ./data is mounted into the api container at /app/data
• nginx in web serves the SPA and proxies /api/* and /healthz to api:8888
• external traffic stays same-origin even though containers are split
• auth.db lives inside the mounted data/ directory

Project Structure

always-on-memory-agent/
├── agent.py
├── server.py
├── dashboard.py
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── web/
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── src/
│   └── dist/
├── docs/
└── data/
    ├── auth.db
    └── users/
        └── <user_id>/
            ├── inbox/
            └── memory.db

dashboard.py remains in the repo but is no longer the primary UI path.

Built With

• Google ADK for agent orchestration
• Gemini 3.1 Flash-Lite for LLM operations
• SQLite for auth.db and per-user memory.db
• aiohttp for the API server
• React + shadcn/ui + Tailwind CSS for the web console
• nginx for same-origin reverse proxying in split container deployments

License