.env.example.full

# =============================================================================
# PowerMem — full configuration reference
# =============================================================================
# This file documents every available configuration knob, grouped by component.
# Use it when you want to:
#   - swap providers (Qwen ↔ OpenAI ↔ SiliconFlow ↔ Ollama ↔ ...),
#   - tune database / vector store / graph store performance,
#   - enable optional subsystems (reranker, intelligent memory, telemetry,
#     audit, skill store, etc.).
#
# If you just want to get started, copy `.env.example` (minimal) instead:
#   cp .env.example .env       # ~5 vars, zero-config local embedder
#
# Copy this file to `.env` only when you need more control:
#   cp .env.example.full .env
#
# Notes on defaults:
#   - Database: platform-aware. Linux with embedded SeekDB available defaults
#     to OceanBase/SeekDB on disk; other zero-config platforms default to
#     SQLite for basic local memory CRUD/search. Use OceanBase/SeekDB for the
#     full feature stack.
#   - Embedder: built-in `all-MiniLM-L6-v2` (384 dims) running locally with no
#     API key. Setting EMBEDDING_PROVIDER below switches to a cloud / self-
#     hosted embedder instead.
# =============================================================================

# TIMEZONE — timezone for stored memory timestamps (created_at, updated_at, ...).
#   Leave unset (default) to auto-detect from the host machine; PowerMem falls
#   back to UTC if detection fails. Uncomment to pin a specific IANA zone.
#   Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
# TIMEZONE=Asia/Shanghai

# =============================================================================
# 1. Database (Required) — where memories, vectors, and (optionally) the graph
# live. PowerMem speaks SQL underneath, so any supported backend can hold the
# full memory pipeline.
# =============================================================================
#
# DATABASE_PROVIDER — which storage engine PowerMem talks to.
#   Recommended:  oceanbase  (full capability stack; leave OCEANBASE_HOST empty
#                             for embedded SeekDB on supported Linux installs,
#                             or set OCEANBASE_HOST to point at a remote
#                             OceanBase cluster)
#   Leave unset to use the platform-aware default.
#   Other options: sqlite     (smallest footprint, basic local CRUD/search),
#                  postgres / pgvector (if your stack already runs PostgreSQL)
# DATABASE_PROVIDER=oceanbase

# -----------------------------------------------------------------------------
# OceanBase — used when DATABASE_PROVIDER=oceanbase. The same provider covers
# two deployment shapes:
#   - Embedded seekdb (recommended for zero-config): leave OCEANBASE_HOST
#     empty; data lives on disk under OCEANBASE_PATH, no separate database
#     process is required.
#   - Remote cluster: set OCEANBASE_HOST to your cluster's address.
# -----------------------------------------------------------------------------
# OCEANBASE_HOST — hostname / IP of the cluster.
#   Recommended:  empty   (boots embedded seekdb at OCEANBASE_PATH)
#   Other options: your cluster's hostname / IP for a remote OceanBase setup
OCEANBASE_HOST=
# OCEANBASE_PATH — on-disk directory used by embedded seekdb (i.e. when
# OCEANBASE_HOST is empty). Ignored for remote clusters.
#   Recommended:  ./seekdb_data
#   Other options: any writable absolute path, e.g. /var/lib/powermem/seekdb
OCEANBASE_PATH=./seekdb_data
# OCEANBASE_PORT — SQL listen port on the cluster (used in remote mode).
#   Recommended:  2881   (the standard OceanBase port)
OCEANBASE_PORT=2881
# OCEANBASE_USER / OCEANBASE_PASSWORD — credentials (used in remote mode).
#   Use a dedicated PowerMem user with write access to the target database.
OCEANBASE_USER=root@sys
OCEANBASE_PASSWORD=your_password
# OCEANBASE_DATABASE — logical database name (also used in embedded mode).
#   Recommended:  powermem
OCEANBASE_DATABASE=powermem
# OCEANBASE_COLLECTION — table that stores the main memory rows.
#   Recommended:  memories
OCEANBASE_COLLECTION=memories

## Keep the default settings, as modifications are generally not needed.
# OCEANBASE_INDEX_TYPE — algorithm used to index the dense vector column.
#   Recommended:  HNSW   (best recall on small/medium datasets, low latency)
#   Other options: IVF   (large corpora, 10k+ vectors),
#                  FLAT  (brute force; correct but slow above ~10k rows)
OCEANBASE_INDEX_TYPE=HNSW
# OCEANBASE_VECTOR_METRIC_TYPE — distance function used at query time.
#   Recommended:  cosine          (matches most sentence-embedding models)
#   Other options: l2 (Euclidean), inner_product (fast, normalized vectors)
OCEANBASE_VECTOR_METRIC_TYPE=cosine
# OCEANBASE_EMBEDDING_MODEL_DIMS — vector dimension; must match the embedder.
#   Recommended:  384   (built-in default embedder = all-MiniLM-L6-v2)
#   Other options: 768 / 1024 / 1536 / 3072 — whatever your embedder emits
OCEANBASE_EMBEDDING_MODEL_DIMS=384
# OCEANBASE_TEXT_FIELD / VECTOR_FIELD / PRIMARY_FIELD / METADATA_FIELD /
# VIDX_NAME — column and index names PowerMem reads / writes. Change only
# if you integrate with an existing schema.
OCEANBASE_TEXT_FIELD=document
OCEANBASE_VECTOR_FIELD=embedding
OCEANBASE_PRIMARY_FIELD=id
OCEANBASE_METADATA_FIELD=metadata
OCEANBASE_VIDX_NAME=memories_vidx

# --- Connection pool (remote mode only) --------------------------------------
# Read only when OCEANBASE_HOST is non-empty. Embedded seekdb uses a NullPool
# and ignores these.
# OCEANBASE_POOL_RECYCLE — seconds before a pooled connection is recycled.
#   Recommended:  3600   (one hour; matches most cloud LB idle timeouts)
#   Other options: 1800 (aggressive), 7200+ (long-lived NAT)
OCEANBASE_POOL_RECYCLE=3600
# OCEANBASE_POOL_PRE_PING — run a `SELECT 1` before each connection checkout
# to detect already-dead connections instead of failing the first query.
#   Recommended:  true   (cheap insurance against pool stalls)
#   Other options: false  (skip the round-trip; only with bulletproof networking)
OCEANBASE_POOL_PRE_PING=true

# --- Hybrid / sparse retrieval -----------------------------------------------
# OCEANBASE_INCLUDE_SPARSE — provision a sparse vector column alongside the
# dense one so retrieval can fuse vector + BM25-style sparse matches. The
# generic SPARSE_VECTOR_ENABLE alias (section 14) also resolves here.
#   Recommended:  false  (start dense-only; turn on when you need exact-
#                         keyword recall — IDs, error codes, etc.)
#   Other options: true   (requires embedded seekdb ≥1.3 or OceanBase ≥4.5;
#                          also configure section 14 for the sparse embedder)
OCEANBASE_INCLUDE_SPARSE=false
# OCEANBASE_ENABLE_NATIVE_HYBRID — push the hybrid (dense + full-text +
# sparse) ranking down into a single SQL call using the engine's native
# hybrid extension instead of fusing scores in Python.
#   Recommended:  false  (safe default for older OceanBase clusters)
#   Other options: true   (requires embedded seekdb ≥1.3 or OceanBase ≥4.5;
#                          lower latency and less network chatter at scale)
OCEANBASE_ENABLE_NATIVE_HYBRID=false

# -----------------------------------------------------------------------------
# SQLite — lightweight, dependency-free, single-file storage for development,
# CI, and tiny deployments. No vector index; relies on a Python-side scan.
# Use only when the OceanBase embedded-seekdb mode is not an option.
# -----------------------------------------------------------------------------
# SQLITE_PATH — file the database is written to (parent dirs auto-created).
#   Recommended:  ./data/powermem_dev.db
#   Other options: :memory: (ephemeral, for tests only) or any writable path
SQLITE_PATH=./data/powermem_dev.db
# SQLITE_ENABLE_WAL — Write-Ahead Logging for better concurrent read perf.
#   Recommended:  true   (safer with concurrent readers; tiny disk overhead)
#   Other options: false  (only set this if you need rollback-journal mode)
SQLITE_ENABLE_WAL=true
# SQLITE_TIMEOUT — seconds to wait for a database lock before raising.
#   Recommended:  30   (tolerates short write contention)
#   Other options: any positive number; raise for write-heavy bursts
SQLITE_TIMEOUT=30
SQLITE_COLLECTION=memories

# -----------------------------------------------------------------------------
# PostgreSQL (via pgvector) — use when your environment already runs Postgres
# and you want memories in the same operational store.
# -----------------------------------------------------------------------------
POSTGRES_HOST=127.0.0.1
# POSTGRES_PORT — standard Postgres listen port.
#   Recommended:  5432
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=powermem
POSTGRES_COLLECTION=memories

## Keep the default settings, as modifications are generally not needed.
POSTGRES_EMBEDDING_MODEL_DIMS=1536
# POSTGRES_DISKANN / POSTGRES_HNSW — which vector index extensions are
# available and should be used. Enable whichever your Postgres instance has.
#   Recommended (single index): HNSW=true, DISKANN=false   (works on plain
#                                                           pgvector ≥0.5)
#   Other options:               DISKANN=true (requires the diskann extension,
#                                              better for very large corpora)
POSTGRES_DISKANN=true
POSTGRES_HNSW=true
# DATABASE_SSLMODE / POOL_SIZE / MAX_OVERFLOW — uncomment to tighten the
# connection pool or force TLS. Defaults are safe for development.
# DATABASE_SSLMODE=prefer
# DATABASE_POOL_SIZE=10
# DATABASE_MAX_OVERFLOW=20


# =============================================================================
# 2. LLM (Required) — the chat model PowerMem calls to extract facts from raw
# input, decide what to add/update/skip in memory, and synthesize search-time
# answers. The quality and cost of every memory and every retrieval flow
# through this model.
# =============================================================================
#
# LLM_PROVIDER — which gateway to call.
#   Recommended:  openai
#     The `openai` provider speaks the OpenAI chat-completions protocol — the
#     de-facto standard. ANY OpenAI-compatible model can run through it (Qwen
#     incl. the "coding plan", DeepSeek, SiliconFlow, vLLM, Ollama, ...): keep
#     LLM_PROVIDER=openai and point OPENAI_LLM_BASE_URL (below) at that vendor's
#     OpenAI-compatible endpoint, then set LLM_MODEL to its model name.
#   Other (native) options: anthropic, qwen, siliconflow, deepseek,
#                  ollama / vllm — only needed for vendor-specific features the
#                  plain OpenAI protocol can't express (e.g. Anthropic's API).
LLM_PROVIDER=openai

# LLM_API_KEY — credential for the chosen provider. Ignored for local
# providers (`ollama`, `vllm`). See `.env.example` for the per-provider
# console URL where you get a key.
LLM_API_KEY=your_api_key_here

# LLM_MODEL — the specific model on the chosen endpoint.
#   Recommended:  gpt-4o-mini (cheap, fast, solid extraction quality)
#   Other OpenAI models:         gpt-4o, gpt-4.1, gpt-4-turbo
#   Via OPENAI_LLM_BASE_URL:     the target endpoint's own model name, e.g.
#                                qwen-plus / qwen-max (Qwen compatible-mode),
#                                deepseek-chat (DeepSeek)
#   For `anthropic`:             claude-sonnet-4-6, claude-haiku-4-5
#   For `ollama` / `vllm`:       any model you've pulled locally
#                                (e.g. llama3.1:8b, qwen2.5:7b)
LLM_MODEL=gpt-4o-mini

## Keep the default settings, as modifications are generally not needed.
# LLM_TEMPERATURE — sampling temperature; higher = more creative, lower = more
# deterministic. Memory extraction prefers deterministic output.
#   Recommended:  0.7   (works well for extraction + Q&A)
#   Other options: 0.0–0.3 for strict extraction; up to 1.0 for free-form Q&A
LLM_TEMPERATURE=0.7
# LLM_MAX_TOKENS — cap on generated tokens per call. Raise it if extraction or
# answers get truncated; lower it to bound cost.
#   Recommended:  1000
#   Other options: 512 (cheap, short answers); 2000+ (long answers / large
#                  fact extraction batches)
LLM_MAX_TOKENS=1000
# LLM_TOP_P / LLM_TOP_K — nucleus / top-k sampling. Keep defaults unless you
# specifically need different randomness behaviour.
LLM_TOP_P=0.8
LLM_TOP_K=50
# LLM_ENABLE_SEARCH — Qwen-only: lets the model consult web search inside its
# own call. Costs extra tokens; only useful when memories need fresh facts.
#   Recommended:  false  (PowerMem already has its own retrieval pipeline)
#   Other options: true   (only if you specifically want LLM-side web augment)
LLM_ENABLE_SEARCH=false

# Per-provider base URLs.
#
# OPENAI_LLM_BASE_URL is the endpoint the recommended `openai` provider calls.
# Leave it on the official OpenAI URL for OpenAI itself; repoint it to run any
# OpenAI-COMPATIBLE model through the same provider (this is the recommended way
# to use Qwen, DeepSeek, SiliconFlow, vLLM, Ollama, ... — no provider switch
# needed, just the base URL + a matching LLM_MODEL):
#   - OpenAI (default):                 https://api.openai.com/v1
#   - Qwen DashScope compatible-mode
#     (incl. coding plan):             https://dashscope.aliyuncs.com/compatible-mode/v1
#     (international):                  https://dashscope-intl.aliyuncs.com/compatible-mode/v1
#   - DeepSeek:                         https://api.deepseek.com/v1
#   - SiliconFlow:                      https://api.siliconflow.cn/v1
#   - Local vLLM / Ollama:              http://localhost:8000/v1 / http://localhost:11434/v1
OPENAI_LLM_BASE_URL=https://api.openai.com/v1
# Extra headers for OpenAI-compatible LLM gateways. Prefer JSON for multiple
# headers, e.g. {"X-Custom-Header":"your-value"}.
# OPENAI_LLM_DEFAULT_HEADERS=
#
# The remaining URLs are only read when you pick that *native* provider instead
# of routing through `openai` (e.g. LLM_PROVIDER=qwen). Override only when
# fronting the provider with a proxy / self-hosted gateway, or for
# `ollama` / `vllm` where you must point at your local instance.
QWEN_LLM_BASE_URL=https://dashscope.aliyuncs.com/api/v1
SILICONFLOW_LLM_BASE_URL=https://api.siliconflow.cn/v1
OLLAMA_LLM_BASE_URL=
VLLM_LLM_BASE_URL=
ANTHROPIC_LLM_BASE_URL=https://api.anthropic.com
DEEPSEEK_LLM_BASE_URL=https://api.deepseek.com

# =============================================================================
# 3. Embedding (Optional) — the model that turns text into the dense vectors
# stored in the vector store. Higher-quality embeddings = better retrieval
# recall. The block below is wired to the zero-config built-in default; flip
# EMBEDDING_PROVIDER (and the model / dims to match) to use a cloud or
# self-hosted embedder instead.
# =============================================================================
#
# EMBEDDING_PROVIDER — which embedding service PowerMem calls.
#   Recommended:  default   (the built-in local `all-MiniLM-L6-v2`; no API
#                            key, model auto-downloads to ~/.cache on first
#                            use — zero-config, runs entirely locally)
#   Other options: qwen       (cloud; higher recall, needs an API key),
#                  openai     (OpenAI text-embedding family),
#                  siliconflow (OpenAI-compatible; CN-friendly),
#                  huggingface (local sentence-transformers / TEI server),
#                  ollama / lmstudio (fully local via a separate runtime),
#                  azure_openai (Azure-hosted OpenAI embeddings),
#                  gemini     (Google GenAI embedding),
#                  vertexai   (Google Vertex AI embedding),
#                  together   (Together AI),
#                  aws_bedrock (AWS Bedrock embedding),
#                  zai        (Zhipu AI embedding)
EMBEDDING_PROVIDER=default

# EMBEDDING_API_KEY — credential for the chosen provider. Not used by
# `default` (and ignored by `huggingface` direct mode, `ollama`, `lmstudio`).
# Uncomment and fill in when you switch EMBEDDING_PROVIDER to a cloud
# service.
# EMBEDDING_API_KEY=your_api_key_here
# EMBEDDING_MODEL — specific embedding model on the chosen provider.
#   Recommended:  all-MiniLM-L6-v2   (the only model the built-in `default`
#                                     provider supports — match it here for
#                                     clarity / future-proofing)
#   Other options for `qwen`:    text-embedding-v4 (current),
#                                text-embedding-v3 (older, cheaper)
#   For `openai`:                text-embedding-3-large (best, 3072d),
#                                text-embedding-3-small (cheaper, 1536d),
#                                text-embedding-ada-002 (legacy)
#   For `siliconflow`:           BAAI/bge-m3, BAAI/bge-large-zh-v1.5
#   For `huggingface`:           sentence-transformers/all-MiniLM-L6-v2,
#                                bge-m3, etc.
#   For `azure_openai`:          your-deployment-name
#   For `gemini`:                gemini-embedding-001
#   For `zai`:                   embedding-3
EMBEDDING_MODEL=all-MiniLM-L6-v2
# EMBEDDING_DIMS — output vector dimension. MUST match the model above AND
# the OCEANBASE_EMBEDDING_MODEL_DIMS in your storage section.
#   Recommended:  384   (matches the built-in `default` provider)
#   Other options: 768 (bge-base), 1024 (bge-large),
#                  1536 (text-embedding-v4 / text-embedding-3-small),
#                  3072 (text-embedding-3-large)
EMBEDDING_DIMS=384

# Per-provider base URLs. Override only when you front the provider with a
# proxy / self-hosted gateway (e.g. http://localhost:8080/v1 for a local TEI
# server, or http://localhost:11434/v1 for Ollama).
QWEN_EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/api/v1
OPENAI_EMBEDDING_BASE_URL=https://api.openai.com/v1
# Extra headers for OpenAI-compatible embedding gateways. Prefer JSON for
# multiple headers, e.g. {"X-Custom-Header":"your-value"}.
# OPENAI_EMBEDDING_DEFAULT_HEADERS=
# EMBEDDING_OPENAI_PASS_DIMENSIONS — set to `false` for OpenAI-compatible
# gateways that reject Matryoshka / output-dimension overrides
# (e.g. Qwen3-Embedding-8B served via an OpenAI-compatible endpoint).
# EMBEDDING_OPENAI_PASS_DIMENSIONS=false
SILICONFLOW_EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
HUGGINFACE_EMBEDDING_BASE_URL=
LMSTUDIO_EMBEDDING_BASE_URL=
OLLAMA_EMBEDDING_BASE_URL=

# =============================================================================
# 4. Rerank (Optional) — a second-stage model that re-scores the top vector
# hits with a cross-encoder. Cheap recall first (vector + full-text), then
# accurate ordering with the reranker. Improves search precision a lot for
# Q&A use cases at the cost of one extra model call per query.
# =============================================================================
#
# RERANKER_ENABLED — turn the rerank stage on/off.
#   Recommended:  false  (start simple; enable once recall is good and you
#                         want sharper top-k ordering)
#   Other options: true   (enable for Q&A / agent loops where the top result
#                          matters more than coverage)
RERANKER_ENABLED=false
# RERANKER_PROVIDER — which rerank service to call when enabled.
#   Recommended:  qwen   (qwen3-rerank; strong CN/EN performance)
#   Other options: jina    (Jina AI cloud rerank API),
#                  zai     (Zhipu AI rerank),
#                  generic (any standard rerank API — SiliconFlow, Xinference,
#                           vLLM, or other OpenAI-compatible rerank services)
RERANKER_PROVIDER=qwen
# RERANKER_MODEL — specific rerank model.
#   Recommended:  qwen3-rerank   (matches the Qwen provider above)
#   Other options for `jina`:    jina-reranker-v3 (latest),
#                                jina-reranker-v2-base-multilingual
#   For `zai`:                   rerank (default)
#   For `generic`:               depends on backend — see examples below
RERANKER_MODEL=qwen3-rerank
RERANKER_API_KEY=your_api_key_here
# RERANKER_API_BASE_URL — endpoint for the rerank API.
#   For `qwen`:    auto-resolved via DashScope SDK (override not needed)
#   For `jina`:    https://api.jina.ai/v1/rerank (default)
#   For `zai`:     https://open.bigmodel.cn/api/paas/v4/rerank (default)
#   For `generic`: REQUIRED — set to your service endpoint, e.g.:
#                  https://api.siliconflow.cn/v1/rerank (SiliconFlow)
#                  http://localhost:9997/v1/rerank      (Xinference local)
# RERANKER_API_BASE_URL=

# Each provider also accepts its native keys / URLs if RERANKER_* is unset:
#   Qwen:     DASHSCOPE_API_KEY + DASHSCOPE_BASE_URL
#   Jina:     JINA_API_KEY      + JINA_API_BASE_URL
#   Zhipu AI: ZAI_API_KEY       + ZAI_API_BASE_URL

# --- Example: SiliconFlow rerank via `generic` provider ---
# RERANKER_ENABLED=true
# RERANKER_PROVIDER=generic
# RERANKER_MODEL=BAAI/bge-reranker-v2-m3
# RERANKER_API_BASE_URL=https://api.siliconflow.cn/v1/rerank
# RERANKER_API_KEY=your_siliconflow_api_key

# --- Example: Local Xinference rerank via `generic` provider ---
# RERANKER_ENABLED=true
# RERANKER_PROVIDER=generic
# RERANKER_MODEL=bge-reranker-v2-m3
# RERANKER_API_BASE_URL=http://localhost:9997/v1/rerank
# RERANKER_API_KEY=

# =============================================================================
# 5. Agent (Optional) — controls how memories are scoped, shared, and
# protected across multiple agents / users in the same database. Most
# single-user, single-app deployments can leave this section at the defaults.
# =============================================================================
#
# AGENT_ENABLED — turn agent-aware memory routing on/off.
#   Recommended:  true   (safe even for single-agent apps; the cost is zero)
#   Other options: false  (only if you intentionally want a flat, unscoped
#                          memory pool)
AGENT_ENABLED=true
# AGENT_DEFAULT_SCOPE — default visibility scope of a new memory.
#   Recommended:  AGENT       (memories belong to the agent that wrote them)
#   Other options: USER       (cross-agent, per user),
#                  GLOBAL     (shared across the whole deployment)
AGENT_DEFAULT_SCOPE=AGENT
# AGENT_DEFAULT_PRIVACY_LEVEL — privacy tag stamped on new memories.
#   Recommended:  PRIVATE   (locked to the owner)
#   Other options: PUBLIC, RESTRICTED
AGENT_DEFAULT_PRIVACY_LEVEL=PRIVATE
# AGENT_DEFAULT_COLLABORATION_LEVEL — how other agents may interact with
# someone else's memories by default.
#   Recommended:  READ_ONLY   (collaborate without overwriting)
#   Other options: NONE (full isolation), READ_WRITE (open collaboration)
AGENT_DEFAULT_COLLABORATION_LEVEL=READ_ONLY
# AGENT_DEFAULT_ACCESS_PERMISSION — default ACL applied to new memories.
#   Recommended:  OWNER_ONLY
#   Other options: TEAM, PUBLIC
AGENT_DEFAULT_ACCESS_PERMISSION=OWNER_ONLY

# AGENT_MEMORY_MODE — how PowerMem partitions memory across agents/users.
#   Recommended:  auto         (chosen from the agent_id / user_id you pass at
#                               call time — works for almost everyone)
#   Other options: multi_agent (force agent-scoped layout),
#                  multi_user  (force user-scoped layout),
#                  hybrid      (both axes; for shared-team agents)
AGENT_MEMORY_MODE=auto


# =============================================================================
# 6. Intelligent Memory (Optional) — Ebbinghaus-style time decay so memories
# fade unless reinforced by access, and tiered "working / short-term /
# long-term" retention thresholds drive search ranking. Disable only if you
# want a pure append-only memory log.
# =============================================================================
#
# INTELLIGENT_MEMORY_ENABLED — turn the decay/reinforcement pipeline on.
#   Recommended:  true
#   Other options: false  (treat all memories as equally fresh forever)
INTELLIGENT_MEMORY_ENABLED=true
# INTELLIGENT_MEMORY_INITIAL_RETENTION — strength assigned to a memory the
# moment it's first stored (1.0 = fully retained).
#   Recommended:  1.0
INTELLIGENT_MEMORY_INITIAL_RETENTION=1.0
# INTELLIGENT_MEMORY_DECAY_RATE — how quickly retention falls over time
# (higher = faster forgetting).
#   Recommended:  0.1
#   Other options: 0.05 (slower fade, larger working set),
#                  0.2  (more aggressive forgetting)
INTELLIGENT_MEMORY_DECAY_RATE=0.1
# INTELLIGENT_MEMORY_REINFORCEMENT_FACTOR — how much retention recovers each
# time a memory is hit / accessed.
#   Recommended:  0.3
#   Other options: 0.1–0.5
INTELLIGENT_MEMORY_REINFORCEMENT_FACTOR=0.3
# WORKING / SHORT_TERM / LONG_TERM thresholds — retention cutoffs that bucket
# memories into the three tiers (anything below WORKING is effectively
# forgotten unless reinforced).
#   Recommended:  0.3 / 0.6 / 0.8
INTELLIGENT_MEMORY_WORKING_THRESHOLD=0.3
INTELLIGENT_MEMORY_SHORT_TERM_THRESHOLD=0.6
INTELLIGENT_MEMORY_LONG_TERM_THRESHOLD=0.8

# Memory decay calculation — same idea, applied per-write at the storage
# layer. Keep aligned with INTELLIGENT_MEMORY_* above.
MEMORY_DECAY_ENABLED=true
# MEMORY_DECAY_ALGORITHM — decay function.
#   Recommended:  ebbinghaus   (matches the classical forgetting curve)
#   Other options: linear, exponential
MEMORY_DECAY_ALGORITHM=ebbinghaus
MEMORY_DECAY_BASE_RETENTION=1.0
MEMORY_DECAY_FORGETTING_RATE=0.1
MEMORY_DECAY_REINFORCEMENT_FACTOR=0.3

# INTELLIGENT_MEMORY_FALLBACK_TO_SIMPLE_ADD — when the LLM extraction step
# fails (rate limit / parse error), should PowerMem still persist the raw
# input as a memory?
#   Recommended:  false  (skip noisy fallbacks; surface the error instead)
#   Other options: true   (best-effort capture; useful for audit / data loss
#                          prevention scenarios)
INTELLIGENT_MEMORY_FALLBACK_TO_SIMPLE_ADD=false


# =============================================================================
# 7. Performance (Optional) — batch sizes, in-memory caches, and search
# limits. Defaults are tuned for development; raise the batch / cache numbers
# in production once you've measured.
# =============================================================================
#
# MEMORY_BATCH_SIZE — how many memories are processed in a single internal
# batch (extraction, embedding, write).
#   Recommended:  100
#   Other options: 50 (slower hardware), 200–500 (large ingest jobs)
MEMORY_BATCH_SIZE=100
# MEMORY_CACHE_SIZE — number of recently-read memories kept in process.
#   Recommended:  1000
#   Other options: 200 (RAM-constrained), 5000+ (read-heavy workloads)
MEMORY_CACHE_SIZE=1000
# MEMORY_CACHE_TTL — seconds before a cached memory is re-fetched from store.
#   Recommended:  3600  (one hour; fresh enough for most apps)
#   Other options: 300 (highly-mutable data), 86400 (mostly-static memories)
MEMORY_CACHE_TTL=3600
# MEMORY_SEARCH_LIMIT — default top-k returned by `memory.search()`.
#   Recommended:  10
#   Other options: 3–5 (precision-first Q&A), 20–50 (broad context for agents)
MEMORY_SEARCH_LIMIT=10
# MEMORY_SEARCH_THRESHOLD — minimum similarity score required to surface a
# hit (range 0.0–1.0, cosine).
#   Recommended:  0.7   (drops low-quality matches without being too strict)
#   Other options: 0.5 (keep more recall), 0.85 (strict precision)
MEMORY_SEARCH_THRESHOLD=0.7

# Vector store batching / caching — same idea, applied at the storage layer.
# VECTOR_STORE_BATCH_SIZE — rows per write batch sent to the backend.
#   Recommended:  50
#   Other options: 200–1000 for bulk ingests against OceanBase / pgvector
VECTOR_STORE_BATCH_SIZE=50
VECTOR_STORE_CACHE_SIZE=500
# VECTOR_STORE_INDEX_REBUILD_INTERVAL — seconds between optional background
# index optimization passes.
#   Recommended:  86400  (once a day; minimal disruption)
#   Other options: 3600 (high-churn workloads), 0 (never)
VECTOR_STORE_INDEX_REBUILD_INTERVAL=86400


# =============================================================================
# 8. Security (Optional) — at-rest encryption of memory text and per-user
# access control. Enable when memories may contain PII / regulated data.
# =============================================================================
#
# ENCRYPTION_ENABLED — encrypt memory payloads before storing them.
#   Recommended:  false  (start without; enable once you have a real KMS)
#   Other options: true   (then ENCRYPTION_KEY MUST be set to a 32-byte key,
#                          preferably loaded from a secret manager)
ENCRYPTION_ENABLED=false
ENCRYPTION_KEY=
# ENCRYPTION_ALGORITHM — symmetric cipher used when encryption is on.
#   Recommended:  AES-256-GCM   (authenticated; widely supported)
#   Other options: AES-256-CBC   (legacy compatibility only)
ENCRYPTION_ALGORITHM=AES-256-GCM

# ACCESS_CONTROL_ENABLED — turn on ACL enforcement at the API boundary.
#   Recommended:  true   (defence in depth; cheap to keep on)
#   Other options: false  (single-tenant dev environments)
ACCESS_CONTROL_ENABLED=true
# ACCESS_CONTROL_DEFAULT_PERMISSION — what a brand-new user can do by default.
#   Recommended:  READ_ONLY
#   Other options: READ_WRITE, NONE
ACCESS_CONTROL_DEFAULT_PERMISSION=READ_ONLY
# ACCESS_CONTROL_ADMIN_USERS — comma-separated user ids granted full access.
#   Recommended:  set to your operator account(s); avoid using `root` in prod
ACCESS_CONTROL_ADMIN_USERS=admin,root


# =============================================================================
# 9. Telemetry (Optional) — anonymized usage analytics streamed to the
# PowerMem hosted endpoint to help guide development. Fully opt-in.
# =============================================================================
#
# TELEMETRY_ENABLED — turn telemetry on.
#   Recommended:  false  (off by default; only enable if you want to send
#                         usage data)
#   Other options: true   (send anonymized events to TELEMETRY_ENDPOINT)
TELEMETRY_ENABLED=false
TELEMETRY_ENDPOINT=https://telemetry.powermem.ai
TELEMETRY_API_KEY=
# TELEMETRY_BATCH_SIZE / FLUSH_INTERVAL / RETENTION_DAYS — buffering and
# server-side retention knobs. Defaults are safe; tune only on very high
# event volumes.
TELEMETRY_BATCH_SIZE=100
TELEMETRY_FLUSH_INTERVAL=30
TELEMETRY_RETENTION_DAYS=30


# =============================================================================
# 10. Audit (Optional) — local append-only log of who did what (memory
# add/update/delete). Compliance-oriented; cheap to keep on.
# =============================================================================
#
# AUDIT_ENABLED — write an audit record per state-changing call.
#   Recommended:  true   (always-on is recommended for any shared deployment)
#   Other options: false  (single-developer use; nothing to audit)
AUDIT_ENABLED=true
AUDIT_LOG_FILE=./logs/audit.log
# AUDIT_LOG_LEVEL — verbosity of audit lines.
#   Recommended:  INFO   (one line per actionable event)
#   Other options: DEBUG (verbose; include request bodies), WARNING (errors only)
AUDIT_LOG_LEVEL=INFO
# AUDIT_RETENTION_DAYS — how long to keep rotated audit logs on disk.
#   Recommended:  90    (typical compliance window)
#   Other options: 30 (lean), 365+ (regulated industries)
AUDIT_RETENTION_DAYS=90
AUDIT_COMPRESS_LOGS=true
AUDIT_LOG_ROTATION_SIZE=100MB


# =============================================================================
# 11. Logging (Optional) — where PowerMem writes its application logs and at
# what verbosity. Independent of the audit log above.
# =============================================================================
#
# LOGGING_LEVEL — minimum severity written to the file sink.
#   Recommended:  DEBUG  (during development / first integration)
#   Other options: INFO   (production default — much less noise),
#                  WARNING / ERROR (only for very quiet ops environments)
LOGGING_LEVEL=DEBUG
LOGGING_FORMAT=%(asctime)s - %(name)s - %(levelname)s - [%(request_id)s] [%(user_id)s] [%(agent_id)s] - %(message)s
LOGGING_FILE=./logs/powermem.log
# LOGGING_MAX_SIZE / BACKUP_COUNT / COMPRESS_BACKUPS — log rotation.
#   Recommended:  100MB / 5 files / compressed
#   Other options: tune up on high-volume servers (e.g. 500MB, 10 files)
LOGGING_MAX_SIZE=100MB
LOGGING_BACKUP_COUNT=5
LOGGING_COMPRESS_BACKUPS=true

# Console (stdout) sink — independent of the file sink above.
LOGGING_CONSOLE_ENABLED=true
# LOGGING_CONSOLE_LEVEL — verbosity at stdout.
#   Recommended:  INFO   (clean console; full detail still goes to the file)
#   Other options: DEBUG (mirror everything), WARNING (silent unless something
#                  is wrong)
LOGGING_CONSOLE_LEVEL=INFO
LOGGING_CONSOLE_FORMAT=%(levelname)s - %(message)s


# =============================================================================
# 12. Skill Store (Optional) — a second, structured store for *skills*:
# reusable step-by-step procedures the agent has learned ("how to refund an
# order", "how to spin up a VM"). Different from raw memory facts. Requires a
# backend with vector + fulltext support (i.e. seekdb or OceanBase).
# =============================================================================
#
# SKILL_STORE_ENABLED — turn the skill store on.
#   Recommended:  false  (start with plain memory; enable once you have
#                         repeated multi-step procedures worth distilling)
#   Other options: true   (then make sure DATABASE_PROVIDER is oceanbase —
#                          sqlite / postgres are not supported here)
SKILL_STORE_ENABLED=false
# SKILL_STORE_COLLECTION_NAME — custom table name; defaults to
# `{vector store collection}_skills` when left unset.
# SKILL_STORE_COLLECTION_NAME=
# SKILL_STORE_SIMILARITY_THRESHOLD — cosine threshold above which two skills
# are treated as duplicates (the newer one is merged into the older).
#   Recommended:  0.75
#   Other options: 0.65 (aggressive merging — fewer, broader skills),
#                  0.85 (conservative — keep near-duplicates separate)
SKILL_STORE_SIMILARITY_THRESHOLD=0.75

# =============================================================================
# 12b. Source Store (Optional) — fact-source linking / provenance.
# When enabled, memory.add() persists the raw input as a ``source`` record
# and links every extracted fact back to it via a ``{collection}_sources`` +
# ``{collection}_sources_memory_links`` table pair. Sources carry the same four
# scope columns as the main memory table (user_id / agent_id / run_id /
# actor_id) so that provenance can be queried or purged along the same axes.
# Currently only the OceanBase storage backend is supported.
# =============================================================================
SOURCE_STORE_ENABLED=false
# Custom base table name (default: {collection}_sources; the link table
# is always ``{base}_memory_links`` / ``{base}_skill_links``).
# SOURCE_STORE_COLLECTION_NAME=

# =============================================================================
# 13. Graph Store (Optional) — knowledge-graph layer for entities and the
# relations between them, in addition to the dense-vector memories above.
# Enables multi-hop retrieval ("everything connected to entity X within 2
# hops"). Requires the OceanBase provider.
# =============================================================================
#
# GRAPH_STORE_ENABLED — turn the graph layer on.
#   Recommended:  false  (start with vector + full-text only; enable when
#                         your queries genuinely need multi-hop traversal)
#   Other options: true
GRAPH_STORE_ENABLED=false

# GRAPH_STORE_PROVIDER — which backend hosts the graph.
#   Recommended:  oceanbase  (the same provider used by the vector store;
#                             leave GRAPH_STORE_HOST blank for embedded
#                             seekdb mode, set it for a remote cluster)
GRAPH_STORE_PROVIDER=oceanbase

# Connection to the graph backend. Defaults below assume a local OceanBase
# embedded-seekdb instance; leave HOST blank for embedded mode, or set it
# to a remote cluster's address.
GRAPH_STORE_HOST=127.0.0.1
GRAPH_STORE_PORT=2881
GRAPH_STORE_USER=root@sys
GRAPH_STORE_PASSWORD=your_password
GRAPH_STORE_DB_NAME=powermem

# GRAPH_STORE_MAX_HOPS — maximum traversal depth at query time.
#   Recommended:  3   (covers most "X is related to Y via Z" queries)
#   Other options: 1–2 (cheaper, narrower), 4–5 (broader; cost grows fast)
GRAPH_STORE_MAX_HOPS=3

# Optional: vector / index settings on the graph node embeddings (same
# semantics as the OCEANBASE_* counterparts in section 1).
# GRAPH_STORE_VECTOR_METRIC_TYPE=l2
# GRAPH_STORE_INDEX_TYPE=HNSW

# Optional: override the LLM prompts used by the graph extraction /
# update / delete pipelines. Leave commented to use the curated defaults.
# GRAPH_STORE_CUSTOM_PROMPT=
# GRAPH_STORE_CUSTOM_EXTRACT_RELATIONS_PROMPT=
# GRAPH_STORE_CUSTOM_UPDATE_GRAPH_PROMPT=
# GRAPH_STORE_CUSTOM_DELETE_RELATIONS_PROMPT=

# =============================================================================
# 14. Sparse Embedding (Optional) — adds a sparse (BM25-like) vector beside
# the dense one, so retrieval can match exact-keyword queries (names, codes,
# rare tokens) that dense embeddings tend to miss. Requires the OceanBase
# provider (embedded seekdb ≥1.3 or remote OceanBase ≥4.5); sqlite /
# pgvector do not support sparse vectors today.
# =============================================================================
#
# SPARSE_VECTOR_ENABLE — turn sparse retrieval on.
#   Recommended:  false  (start dense-only; enable when you see queries that
#                         need exact-keyword recall — IDs, error codes, etc.)
#   Other options: true
SPARSE_VECTOR_ENABLE=false
# SPARSE_EMBEDDER_PROVIDER — which API produces the sparse vectors.
#   Recommended:  qwen   (text-embedding-v4 emits a sparse output natively)
#   Other options: openai
SPARSE_EMBEDDER_PROVIDER=qwen

SPARSE_EMBEDDER_API_KEY=your_api_key_here
SPARSE_EMBEDDER_MODEL=text-embedding-v4
SPARSE_EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/api/v1

# =============================================================================
# 15. Query Rewrite (Optional) — rewrites the raw user query with an LLM
# before searching, to normalize phrasing / expand abbreviations / add
# synonyms. Improves recall on noisy or terse queries at the cost of one LLM
# call per search.
# =============================================================================
#
# QUERY_REWRITE_ENABLED — turn rewriting on.
#   Recommended:  false  (start without; enable once you see retrieval
#                         miss obvious matches due to phrasing)
#   Other options: true
QUERY_REWRITE_ENABLED=false
# QUERY_REWRITE_PROMPT — custom rewrite prompt. Leave commented to use the
# built-in default tuned for memory retrieval.
# QUERY_REWRITE_PROMPT=
# QUERY_REWRITE_MODEL_OVERRIDE — model to use for rewriting; defaults to the
# main LLM_MODEL above. Keep aligned with your main LLM provider for the
# cheapest / lowest-latency calls.
# QUERY_REWRITE_MODEL_OVERRIDE=

# =============================================================================
# 16. HTTP API Server — only used when you run `powermem-server`. These knobs
# do not affect the SDK / CLI flows. Skip the whole section if you only use
# `from powermem import Memory`.
# =============================================================================

# --- Bind --------------------------------------------------------------------
# POWERMEM_SERVER_HOST — interface to bind on.
#   Recommended:  0.0.0.0  (listen on all interfaces; needed inside containers)
#   Other options: 127.0.0.1 (loopback only; safest for desktop / dev)
POWERMEM_SERVER_HOST=0.0.0.0
# POWERMEM_SERVER_PORT — TCP port.
#   Recommended:  8848
#   Other options: any free port; align with your reverse proxy
POWERMEM_SERVER_PORT=8848
# POWERMEM_SERVER_WORKERS — uvicorn worker processes (multi-process serving).
# Ignored when RELOAD=true. Pick ~ CPU cores for stateless workloads.
#   Recommended:  4
#   Other options: 1 (debug), 8+ (heavy throughput)
POWERMEM_SERVER_WORKERS=4
# POWERMEM_SERVER_RELOAD — auto-reload on source change. Single-process only.
#   Recommended:  false  (production)
#   Other options: true   (local development)
POWERMEM_SERVER_RELOAD=false

# --- Authentication ----------------------------------------------------------
# POWERMEM_SERVER_AUTH_ENABLED — require an API key on every request.
#   Default:  false  (zero-config local / test; works out of the box with no key)
#   Set to:   true   (any time the server is reachable from the network — then
#                     also set POWERMEM_SERVER_API_KEYS to a comma-separated list)
POWERMEM_SERVER_AUTH_ENABLED=false
# POWERMEM_SERVER_API_KEYS — comma-separated list of accepted keys.
#   Example: POWERMEM_SERVER_API_KEYS=key1,key2,key3
POWERMEM_SERVER_API_KEYS=

# --- Rate limiting -----------------------------------------------------------
# POWERMEM_SERVER_RATE_LIMIT_ENABLED — per-IP throttling.
#   Recommended:  true
#   Other options: false  (trust your upstream proxy to do this)
POWERMEM_SERVER_RATE_LIMIT_ENABLED=true
# POWERMEM_SERVER_RATE_LIMIT_PER_MINUTE — calls/min/IP before throttling.
#   Recommended:  100
#   Other options: 30 (strict), 1000+ (server-to-server use)
POWERMEM_SERVER_RATE_LIMIT_PER_MINUTE=100

# --- Server-side logging -----------------------------------------------------
POWERMEM_SERVER_LOG_FILE=server.log
# POWERMEM_SERVER_LOG_LEVEL — DEBUG / INFO / WARNING / ERROR / CRITICAL.
#   Recommended:  INFO   (production)
#   Other options: DEBUG (dev), WARNING (very quiet ops)
POWERMEM_SERVER_LOG_LEVEL=INFO
# POWERMEM_SERVER_LOG_FORMAT — `json` or `text`.
#   Recommended:  json   (machine-parseable; required by most log shippers)
#   Other options: text   (human-readable in the terminal)
POWERMEM_SERVER_LOG_FORMAT=json

# --- API metadata (shown in Swagger UI) --------------------------------------
POWERMEM_SERVER_API_TITLE=PowerMem API
POWERMEM_SERVER_API_VERSION=v1
POWERMEM_SERVER_API_DESCRIPTION=PowerMem HTTP API Server - Intelligent Memory System

# --- CORS --------------------------------------------------------------------
# POWERMEM_SERVER_CORS_ENABLED — needed for browser-based clients.
#   Recommended:  true   (most dashboards / web UIs need this)
#   Other options: false  (server-to-server only)
POWERMEM_SERVER_CORS_ENABLED=true
# POWERMEM_SERVER_CORS_ORIGINS — comma-separated allowlist.
#   Recommended:  set to your dashboard origin(s),
#                 e.g. https://memory.example.com,http://localhost:3000
#   Other options: *  (open; only safe inside a trusted private network)
POWERMEM_SERVER_CORS_ORIGINS=*

# =============================================================================
# 17. Custom Prompts (Optional) — override the LLM prompts used by the memory
# extraction pipeline. Leave commented to use the built-in defaults, which
# have been tuned against the public benchmarks (LOCOMO, AppWorld).
# =============================================================================
# Tip: usually the right move is to tweak the *user-provided* context you pass
# to `memory.add()`, not these system prompts. Touch these only when you have
# a specific behaviour the defaults cannot express.

# Replaces the default FACT_RETRIEVAL_PROMPT used to extract facts from raw input.
# POWERMEM_CUSTOM_FACT_EXTRACTION_PROMPT=

# Replaces the default UPDATE_MEMORY_PROMPT used to decide add / update / skip.
# POWERMEM_CUSTOM_UPDATE_MEMORY_PROMPT=

# Replaces the default importance scoring prompt (drives retention weighting).
# POWERMEM_CUSTOM_IMPORTANCE_EVALUATION_PROMPT=