Skip to content

configuration.md

Latest commit

 

History

History
97 lines (77 loc) · 4.78 KB

configuration.md

File metadata and controls

97 lines (77 loc) · 4.78 KB
Raw

Configuration reference

Sessions has three distinct configuration surfaces: local indexing, the self-hosted HTTP client, and the sessions-serve data plane. Do not put a Postgres DSN in a client process; clients use the authenticated /v1 API.

Local index

Variable Behavior
HASNA_SESSIONS_DIR Sessions data directory. Default: ~/.hasna/sessions.
HASNA_SESSIONS_DB_PATH Explicit SQLite path. Takes precedence over SESSIONS_DB_PATH and the data-directory default. :memory: is supported.
SESSIONS_DB_PATH Compatibility alias for the explicit SQLite path.
HASNA_MACHINE Override the machine name stored with ingested sessions.
CLAUDE_PATH Claude base directory; sessions are read from its projects/ child. Default: ~/.claude.
CODEX_PATH Codex base directory; sessions are read from its sessions/ child. Default: ~/.codex.
CODEX_HOME Codex base directory used by the cross-adapter MCP import tools. Default: ~/.codex. Indexed ingestion uses CODEX_PATH instead.
CODEWITH_PATH Codewith base directory; sessions are read from its sessions/ child. Default: ~/.codewith.
GEMINI_PATH Gemini base directory; sessions are read from its tmp/ child. Default: ~/.gemini.
OPENAI_API_KEY Enables embedding generation and semantic search. Full-text search does not require it.
HASNA_SESSIONS_REBUILD_FTS_ON_OPEN=1 Rebuild repaired FTS reference tables on database open when counts differ. Intended for recovery.

If ~/.hasna/sessions/sessions.db does not exist but the legacy ~/.sessions/sessions.db does, the legacy database is copied automatically.

Handoff source hints

sessions handoff prefers explicit --source-session and --source-transcript values. When they are omitted, Claude hooks may supply CLAUDE_SESSION_ID, CLAUDE_CODE_SESSION_ID, or CLAUDECODE_SESSION_ID and CLAUDE_TRANSCRIPT_PATH, CLAUDE_CODE_TRANSCRIPT_PATH, or CLAUDECODE_TRANSCRIPT_PATH. Codewith hooks may supply CODEWITH_SESSION_ID or CODEWITH_THREAD_ID. These values identify source context; they are not storage credentials.

Self-hosted client

Configure the sessions CLI, MCP active-store tools, or @hasna/sessions/storage with:

export HASNA_SESSIONS_MODE=self_hosted
export HASNA_SESSIONS_API_URL=https://sessions.example.com
export HASNA_SESSIONS_API_KEY=...

HASNA_SESSIONS_MODE=cloud is accepted as the same client mode. SESSIONS_MODE, SESSIONS_API_URL, and SESSIONS_API_KEY are compatibility aliases used by the shared storage client. Mode plus URL plus key are required; partial self-hosted configuration fails closed.

Variable Behavior
HASNA_SESSIONS_PRODUCTION_HOSTS Comma- or space-separated host suffixes treated as production-like by backfill safety checks.
HASNA_SESSIONS_PRODUCTION=1 Force the backfill production gate regardless of URL.

The generated @hasna/sessions/sdk helper createSessionsClientFromEnv() reads SESSIONS_API_URL and the optional SESSIONS_API_KEY. Explicit constructor options override environment values.

MCP transport

Variable Behavior
MCP_STDIO=1 Select stdio transport.
MCP_HTTP=1 Explicitly select HTTP transport, which is already the default.
MCP_HTTP_PORT HTTP port. Default: 8877; --port takes precedence.

HTTP binds to 127.0.0.1; there is no environment override for the MCP bind address.

Service data plane

sessions-serve defaults to local mode. A self-hosted service uses Postgres:

export HASNA_SESSIONS_STORAGE_MODE=cloud
export HASNA_SESSIONS_DATABASE_URL=postgres://...
export HASNA_SESSIONS_API_SIGNING_KEY=...
sessions-serve migrate
sessions-serve
Variable Behavior
HASNA_SESSIONS_STORAGE_MODE local or cloud; default local. SESSIONS_STORAGE_MODE is an alias. Deprecated remote, hybrid, and self_hosted values normalize to cloud.
HASNA_SESSIONS_DATABASE_URL Canonical Postgres DSN in cloud mode. SESSIONS_DATABASE_URL is the supported alias.
HASNA_SESSIONS_API_SIGNING_KEY Preferred HMAC signing key for /v1 API-key authentication. HASNA_API_SIGNING_KEY is the shared fallback.
PORT HTTP port. Default: 3456.
HOST Bind hostname. Default: 127.0.0.1.
HASNA_SESSIONS_MAX_REQUEST_BODY_SIZE Request-body limit in bytes or units such as 768MiB. Cloud mode defaults to 512MiB.
SESSIONS_SERVE_ENABLE_MCP=1 Also mount MCP at /mcp in the service process.
SESSIONS_MIGRATIONS_DIR Override the directory containing SQL migrations.
PGSSLROOTCERT CA bundle used by verified Postgres TLS modes.

GET /health, /ready, /version, and /openapi.json are unauthenticated. The /v1 data routes require an API key with the appropriate sessions scopes.