Helios
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TZ | No | Container timezone. Listed under mandatory/core settings in the compose example. | UTC |
| HELIOS_API_KEY | No | Shared Bearer/?token= key required for /mcp, /sse, and /export/* when set. Leave empty only on a trusted local network or Tailscale mesh. | |
| MEMORY_DATA_DIR | Yes | Mandatory persistent storage directory for the SQLite WAL memory.db and Markdown exports. | /data |
| HELIOS_GIT_OWNER | No | Optional username/org filter for Git webhook management. | |
| HELIOS_GIT_TOKEN | No | Personal access token with repo/webhook permissions for manage_git_webhooks. | |
| HELIOS_PUBLIC_URL | No | Override base URL used in /setup scripts; auto-detected from proxy headers if empty. | |
| HELIOS_WORD_LIMIT | No | Maximum words per atomic memory fact; live-editable via MCP. | 25 |
| HELIOS_GIT_API_URL | No | Git provider API base URL, e.g. https://git.example.com or https://api.github.com. | |
| HELIOS_WEBHOOK_URL | No | Webhook callback URL, e.g. https://helios.example.com/webhook/git. | |
| HELIOS_GIT_PROVIDER | No | Git provider for conversational webhook management: forgejo, gitea, github, or gitlab. | |
| HELIOS_WEBHOOK_SECRET | No | Shared HMAC-SHA256 secret for verifying POST /webhook/git payloads. Generate with openssl rand -hex 32. | |
| HELIOS_ALLOWED_ORIGINS | No | Allowed CORS origins. | * |
| HELIOS_CHANGELOG_LIMIT | No | Changelog entry limit; live-editable via MCP. | 100 |
| HELIOS_EPISODIC_TTL_DAYS | No | TTL in days for episodic memories; live-editable via MCP. | 14 |
| HELIOS_REQUIRE_WEBHOOK_SECRET | No | Whether to require HELIOS_WEBHOOK_SECRET for webhook verification. | false |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Helios is your centralized architectural memory across IDE and CLI agents. 1. PRE-FLIGHT: Call recall_memories() at the start of any task using the current repo or folder name. 2. STALE PROTOCOL: When a memory is marked [STALE], inspect the referenced anchor_files before acting. 3. UPDATE RULE: If you modify an architecture choice, port, path, or bug fix, call save_memory() or deprecate_memory(). 4. TOKEN BUDGET: Keep facts atomic (<= 25 words). Never store transient code snippets or secrets. 5. UNINSTALL: If the user requests to uninstall Helios ('uninstall helios'), call get_client_setup_bundle(action='uninstall').
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| export_bundleA | Create or overwrite a portable backup archive (helios_portable_bundle.tar.gz) on the server filesystem. Uses the SQLite Online Backup API to capture a crash-safe snapshot of memory.db alongside all Markdown exports without locking concurrent readers or writers, leaving database records untouched. Use export_bundle for server backups and migration snapshots; use get_client_setup_bundle instead to generate IDE/CLI configuration snippets, or recall_memories to query stored facts. |
| manage_git_webhooksA | List, enable, or disable remote Git push webhooks for anchor_files drift detection across Forgejo, Gitea, GitHub, or GitLab. Requires HELIOS_GIT_TOKEN and HELIOS_WEBHOOK_URL (returns manual setup instructions if unconfigured): action='list' audits owned repos, action='enable' installs an HMAC-signed push webhook on each target in repos, and action='disable' deletes only the Helios webhook from the remote repositories without affecting code or stored memories. Always run action='list' and confirm target repos with the user before calling 'enable' or 'disable'. Use manage_git_webhooks to manage remote repository hooks; use manage_server_config to set HELIOS_GIT_* settings, or revalidate_memories to clear [STALE] flags after a push. |
| get_client_setup_bundleA | Generate read-only client onboarding configs, idempotent global agent directives (), and /remember skill files for local AI tools. Supports full client lifecycle management via action: 'install_or_update' outputs non-destructive MCP and directive snippets tailored to client, os_platform, and instance_role ('workstation' vs headless 'server-cli'); 'switch_role' updates role-specific rules; 'uninstall' provides surgical removal instructions that preserve user custom rules. Use get_client_setup_bundle to install, reconfigure, or uninstall Helios on a client machine; use manage_server_config to modify server-side settings, or export_bundle to back up the database. |
| manage_scope_aliasA | Manage project alias mappings and migrate memory scopes in SQLite. action='list' is read-only and returns all aliases plus per-scope active/stale counts; action='set' maps alias to canonical_scope; action='remove' deletes only the alias mapping while leaving stored memories untouched; action='rename' destructively migrates all memories from alias into canonical_scope, registers the alias, and syncs Markdown exports. 'set' and 'rename' require both alias and canonical_scope, while 'remove' requires alias. Use manage_scope_alias to unify repository names or rename projects; use manage_server_config for server tunables or distill_memories to clean up memories within a scope. |
| manage_server_configA | Inspect, override, or reset live Helios runtime settings in SQLite without restarting the server. action='list' returns all settings with secrets redacted; action='set' (requires key and value) persists an immediate runtime override; action='reset' (requires key) removes the SQLite override to revert to environment or default values. Security-locked keys (HELIOS_API_KEY, HELIOS_WEBHOOK_SECRET, MEMORY_DATA_DIR) cannot be altered at runtime, and changing HELIOS_GIT_API_URL or HELIOS_GIT_PROVIDER automatically clears any stored runtime HELIOS_GIT_TOKEN. Use manage_server_config for server-side tunables; use get_client_setup_bundle for local IDE/CLI onboarding or manage_scope_alias for project scope mappings. |
| recall_memoriesA | Search active and stale memories in Helios using SQLite FTS5 BM25 ranking and category priority (rule > fact > preference > episodic). Read-only: resolves scope aliases, merges 'global' rules when include_global=True, returns top priority records when query is empty, and emits a warning if directive_version lags the server. If any returned memory is flagged [STALE], inspect its anchor_files before acting and resolve via revalidate_memories or save_memory. Use recall_memories at task start for current state; use recall_history instead to inspect superseded or archived records. |
| save_memoryA | Create or supersede an atomic memory (<= 25 words) in SQLite and synchronize Markdown scope exports. Saving to an existing (scope, subject) slot or passing replaces_id automatically marks the prior active memory as 'superseded', while identical content is a safe idempotent no-op. Providing repo-relative anchor_files links the memory to Git push webhooks so commits touching those files automatically flag it [STALE]. Use save_memory to add or update facts and rules; use deprecate_memory to archive obsolete facts without replacement, revalidate_memories to clear [STALE] flags when facts remain valid, or distill_memories for bulk cleanup. |
| deprecate_memoryA | Archive an obsolete active or stale memory by ID without deleting its historical audit record. Transitions status to 'archived', sets the valid_to timestamp, logs the deprecation reason in the scope changelog, and updates Markdown exports. Archived records are excluded from recall_memories but remain permanently inspectable via recall_history. Use deprecate_memory when a fact or rule no longer applies and has no replacement; use save_memory instead to overwrite an outdated fact with a new value, or revalidate_memories if a [STALE] memory is still accurate. |
| recall_historyA | Retrieve superseded and archived memory records for a scope to audit configuration history and slot lineage. Read-only: resolves scope aliases and returns up to limit (1-25) historical entries ordered by valid_to descending, including validity timestamps and superseding memory IDs. Use recall_history for time-travel debugging or reviewing retired facts; use recall_memories instead to search current active or [STALE] memories. |
| revalidate_memoriesA | Restore a batch of [STALE] memories back to 'active' status after verifying that changes to their anchor_files did not invalidate them. Clears stale_reason and stale_since for all valid stale IDs in memory_ids and syncs Markdown exports; non-existent or already-active IDs are safely skipped and reported without failing the batch. Use revalidate_memories only when the recorded fact remains accurate after a commit; use save_memory instead to supersede the fact if its value changed, or deprecate_memory if it was removed. |
| distill_memoriesA | Audit scope memory health, suggest duplicate slot consolidations, find semantic contradictions, or prune expired episodic and abandoned stale records. action='audit' (default), 'suggest', and 'contradictions' (requires HELIOS_GEMINI_API_KEY) are read-only diagnostics; action='prune' archives expired episodic notes and stale memories older than stale_age_days, but is gated by dry_run=True by default (set dry_run=False to commit changes and sync Markdown exports). Use distill_memories for periodic scope-wide hygiene; use deprecate_memory to retire a single obsolete memory ID, or save_memory with replaces_id to apply consolidation suggestions. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 11 tools
Each tool targets a distinct operation, and the memory lifecycle tools are cleanly separated by status and intent: current recall, historical recall, create/supersede, archive, revalidate, and bulk hygiene. Descriptions explicitly cross-reference adjacent tools, making misselection unlikely.
All tool names use consistent snake_case with a verb-first pattern such as recall_memories, save_memory, manage_server_config, and revalidate_memories. Minor pluralization differences are predictable and do not break the convention.
Eleven tools is well-scoped for a memory server that also handles backups, client setup, webhooks, aliases, and runtime configuration. Each tool maps to a meaningful operational need without obvious filler.
The surface covers memory creation, supersession, recall, history, archival, revalidation, bulk cleanup, backup export, client onboarding, webhooks, aliases, and runtime config. Minor gaps remain around importing/restoring an exported bundle and direct single-memory retrieval or hard purge, but core workflows are covered.