PAM-OS

Personal AI Memory OS — durable, local-first memory for AI assistants and coding agents.

简体中文 · Usage guide · GitHub

---

PAM-OS gives AI clients persistent personal memory behind a versioned REST API. It retrieves relevant history before a task, captures stable information after a conversation, consolidates repeated evidence into profile traits, and keeps every user's data in a separate SQLite database.

Highlights

• Local first: data stays in SQLite storage that you control.
• Built for agents: Codex, Claude Code, OpenCode, Hermes, or any HTTP client can share one memory service.
• Adaptive memory loop: policy decides when to read, capture, suppress, or consolidate memory.
• Multi-user isolation: human sessions and agent API keys always resolve to one fixed user.
• Web console: inspect memories and profiles, manage API keys and users, and review system status.
• Secure credentials: Argon2id passwords, HttpOnly sessions, CSRF protection, and scoped, revocable Bearer keys.
• Easy deployment: run the published container image or start directly from source.

Web console

The console at http://127.0.0.1:8765/ui makes memory visible and controllable:

• Overview: memory, profile, context-package, and storage totals; recent memories; type distribution; active traits.
• Memories and profile: search stored memories and review consolidated profile traits.
• Access tokens: create independently revocable API keys with expiry and least-privilege scopes, then permanently delete inactive token records when no longer needed.
• User administration: create or disable users, reset passwords, and configure API-key policy.
• System status: inspect versions and storage diagnostics; administrators can also review security-audit events.

Humans sign in with usernames and passwords. AI clients use separate Bearer API keys issued from Access tokens.

Quick start with the published Docker image

The image at ghcr.io/danzhewuju/pam-os:latest is self-contained. You only need Docker: there is no need to clone this repository or install Python, uv, or project dependencies.

Docker Compose demo (recommended)

Create any empty directory and add these two files.

.env:

PAM_OS_SETUP_TOKEN=replace-with-a-long-random-secret

compose.yaml:

services:
  pam-os:
    image: ghcr.io/danzhewuju/pam-os:latest
    container_name: pam-os
    restart: unless-stopped
    ports:
      - "127.0.0.1:8765:8765"
    env_file:
      - .env
    volumes:
      - pam-os-data:/data

volumes:
  pam-os-data:
    name: pam-os-data

Start the service from that directory:

docker compose up -d
docker compose ps

Docker Compose downloads the GHCR image automatically on the first start. The localhost binding keeps PAM-OS private to the host, and the named volume preserves all databases across container recreation.

Initialize and verify

Open http://127.0.0.1:8765/ui, enter PAM_OS_SETUP_TOKEN, and create the first administrator. The setup route closes permanently after the first account is created.

curl -sS http://127.0.0.1:8765/health/live
docker compose logs -f pam-os

Container setting	Value
Image	ghcr.io/danzhewuju/pam-os:latest
Console	http://127.0.0.1:8765/ui
Swagger UI	http://127.0.0.1:8765/docs
Container port	8765
Persistent data	/data
Runtime user	pam (non-root)
Health check	GET /health/live

After initialization, remove PAM_OS_SETUP_TOKEN from .env and run docker compose up -d --force-recreate. The setup credential is no longer needed once the first administrator exists.

Upgrade

The same two local files are enough for future upgrades:

docker compose pull
docker compose up -d

Compose recreates the service with the new image while retaining the pam-os-data volume. Back up that volume as part of normal operations.

docker run alternative

If you do not use Docker Compose, create the same .env file and run:

docker volume create pam-os-data
docker run -d --name pam-os --restart unless-stopped -p 127.0.0.1:8765:8765 --env-file .env -v pam-os-data:/data ghcr.io/danzhewuju/pam-os:latest

docker run also downloads the image automatically when it is not already available locally and does not require a source checkout.

Connect an AI client

The Docker service is already fully deployed at this point. Agent integration is an optional, separate client-side step and is not required to keep the container running.

First sign in to the console and create a separate API key for each agent from Access tokens. Then install the pam-os-memory integration.

Online installation (recommended)

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/danzhewuju/PAM-OS/refs/heads/master/scripts/install.sh | bash -s -- --codex

Windows PowerShell:

& ([scriptblock]::Create((Invoke-RestMethod 'https://raw.githubusercontent.com/danzhewuju/PAM-OS/refs/heads/master/scripts/install.ps1'))) '--codex'

The online installer requires Git and creates or updates its own managed checkout; you do not need to clone the repository manually. You can review install.sh or install.ps1 before running the command.

Install from a local checkout

macOS or Linux:

./scripts/install.sh --codex --repo-dir "$PWD"

Windows PowerShell:

.\scripts\install.ps1 --codex --repo-dir $PWD

Supported targets are codex, claude, opencode, and hermes. Use the matching target flag or --all. The installer prompts for the REST URL and Bearer key, reuses existing settings during updates, and installs the integration only—it does not start the PAM-OS server.

Do not put an API key directly in a command argument. Use the installer's hidden prompt, --rest-token-file, or secure PAM_OS_REST_TOKEN environment injection.

Agent memory loop

Moment	Endpoint	Purpose
Before a history-dependent task	POST /v2/context/prepare	Decide whether memory is needed and return a prompt-ready context package.
After a substantial turn	POST /v2/turns/observe	Capture durable information and learn reusable policy signals.
On an explicit “remember this” request	POST /v2/memory/capture	Store a stable memory directly.
After repeated evidence	POST /v2/memory/consolidate	Promote evidence into stable profile traits.

See docs/usage.md for complete request examples, response formats, validation rules, and the recommended agent workflow.

Configuration and security

PAM-OS resolves configuration in this order:

environment variables > config/pam-os.toml > built-in defaults

The complete reference is config/pam-os.example.toml. Important environment variables are:

Variable	Purpose
PAM_OS_SETUP_TOKEN	One-time first-administrator setup credential.
PAM_OS_DATA_DIR	Root directory for the control and per-user databases; the image defaults to /data.
PAM_OS_CONTROL_DB	Optional explicit path for the identity control database.
PAM_OS_RUNTIME_CACHE_SIZE	Maximum cached per-user runtimes.
PAM_OS_CONFIG	Path to a TOML configuration file.
PAM_OS_HOST / PAM_OS_PORT	Container listener; image defaults are 0.0.0.0 and 8765.
PAM_OS_COOKIE_SECURE	Set to true when the console is served through HTTPS.
PAM_OS_SESSION_TTL_SECONDS	Absolute web-session lifetime.
PAM_OS_SESSION_IDLE_SECONDS	Idle web-session lifetime.

For remote access, put PAM-OS behind an HTTPS reverse proxy, set PAM_OS_COOKIE_SECURE=true, and change the localhost port binding only at that trusted boundary. Never send passwords, session cookies, or Bearer keys over public plain HTTP.

API overview

Public routes are limited to liveness and initial setup status. Console and administrative routes require a password-authenticated web session. Memory routes accept either that session or a scoped, user-bound Bearer API key.

Area	Main routes
Health and metadata	GET /health/live, GET /v2/health/ready, GET /v2/meta
Setup and sessions	POST /v2/setup, POST /v2/auth/login, POST /v2/auth/logout
Current identity and keys	GET /v2/me, GET/POST /v2/me/api-keys
User administration	GET/POST/PATCH /v2/admin/users, password reset, session and key revocation, audit logs
Memory	POST /v2/events, POST /v2/memories/search, POST /v2/memory/capture
Context and policy	POST /v2/memory/should-use, POST /v2/context/prepare, POST /v2/context/compile
Learning and profile	POST /v2/turns/observe, POST /v2/behavior/choice, POST /v2/memory/consolidate, GET /v2/profile
Inspection and maintenance	GET /v2/storage/stats, GET /v2/memory/inspect, POST /v2/reflect, POST /v2/memory/clear

PAM-OS v0.6 exposes the canonical /v2 API and does not provide v1 or unversioned compatibility aliases.

Run from source

Requirements:

• Python 3.11 or newer
• uv (recommended)

Install and start the service:

uv sync
export PAM_OS_SETUP_TOKEN='replace-with-a-long-random-secret'
uv run python -m uvicorn pam_os.api:create_app --factory --host 127.0.0.1 --port 8765

PowerShell uses $env:PAM_OS_SETUP_TOKEN = "replace-with-a-long-random-secret" before the same uv run command.

Without an override, source deployments store data below ~/.pam-os.

Development

uv sync --extra dev
uv run pytest

License

PAM-OS is licensed under the Apache License 2.0.