aether
Provides a built-in Docker inspector plugin that reports Docker Compose services, exposed ports, and running containers.
Integrates with Git repositories to create per-role worktrees for swarm runs, mine fix/revert/crash commit history for preventive scars, and merge verified branches.
Routes formatting/docs work and optional swarm role execution to a local Ollama instance at localhost:11434.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
# AETHER//OS
A local-first memory kernel for AI coding agents. AetherOS gives Claude Code, Cursor, Windsurf and Aider a multi-repo code graph, compressed context, a secret firewall, a memory of past bugs, time-travel snapshots, a git-worktree swarm orchestrator — and a live 3D view of your codebase that lights up as your agent works.
Everything runs on localhost with SQLite. No servers, no accounts, no model downloads. Your API keys
stay in your environment.
$ aether query "how are secrets masked before reaching the agent"
...
224,297 -> 21,000 tokens (-90.6%) across 15 real queries on this repo · p50 33 msWhy
Agents waste most of their context window reading entire files to find one function, they repeat bugs
the team already fixed, and they will happily paste a .env value into a prompt. AetherOS sits between
the agent and the repo:
Problem | AetherOS |
Agent reads 2,000-line files for one function |
|
"What breaks if I change this?" |
|
The same bug comes back | Scars: recorded lessons plus scars mined from |
Secrets leak into prompts | Regex + Shannon-entropy firewall with a reversible in-RAM vault: |
Poisoned dependencies / docs | Prompt-injection detector (hidden comments, bidi unicode, base64 payloads, |
Risky multi-file edits | Content-addressed snapshots with one-command (or one-click) rollback |
Big features |
|
Cost | A router sends formatting/docs work to local Ollama or Haiku, and architecture work to Opus |
Related MCP server: engram-serve
Quickstart
Requires Python ≥ 3.10 and git. Works on Windows, macOS and Linux.
# Windows (PowerShell) — no activation scripts needed
uv venv .venv --python 3.12
uv pip install --python .venv\Scripts\python.exe -e .
.\.venv\Scripts\aether.exe init # index the current repo
.\.venv\Scripts\aether.exe install-mcp # writes .mcp.json (Claude Code) + .cursor/mcp.json
.\.venv\Scripts\aether.exe web --open # 3D dashboard at http://127.0.0.1:7777# macOS / Linux
uv venv && uv pip install -e . # or: python -m venv .venv && .venv/bin/pip install -e .
aether init --link-repo ../frontend # index this repo + a sibling repo
aether install-mcp && aether web --openRestart Claude Code in the project: the aether MCP server shows up with its tools. To share what
the project knows with your team, commit .aether/team_brain.json.gz (aether export-brain).
MCP tools
Tool | What it does |
| Hybrid FTS5-BM25 + TF-IDF vector search, fused with RRF, then packed into a token budget: signatures, docstrings, matching fragments, deps/dependents, scars, savings metrics |
| Transitive dependents, endpoints defined, endpoint consumers in linked repos, risk score |
| Remember a bug and its fix |
| Warnings before editing |
| Time travel (a safety snapshot is taken before every rollback) |
| Secrets + prompt-injection audit (values are never returned) |
| Tokens and USD saved, graph size, security counters, swarm state |
Resources: aether://telemetry, aether://scars, aether://graph/summary, aether://decisions.
CLI
aether init [--link-repo PATH]... aether index [--force] aether link/unlink/repos
aether query "..." [-t 1500] [--json] aether impact FILE aether scan [PATH]
aether scar FILE "error" --fix "..." aether scars [FILE] aether decision TITLE BODY
aether snapshot [LABEL] aether snapshots / diff ID aether rollback ID [-y]
aether swarm "feature" [--execute] aether swarm-status/-execute/-verify/-merge/-cleanup ID
aether route "prompt" aether export-brain / import-brain
aether web [--open] aether tui aether watch aether mcp aether plugins aether benchmarkThe 3D digital twin
aether web serves a self-contained page (Three.js from a CDN, with an automatic Canvas 2D fallback
when you're offline or WebGL is unavailable). Files are nodes clustered by repository and directory,
dependencies are edges, and every kernel event — CONTEXT_QUERY, SCAR_TRIGGERED, SECRET_BLOCKED,
SWARM_STEP, SNAPSHOT_CREATED — sends light pulses from the core to the files involved, live over
/ws/telemetry. Events are shared through SQLite, so the dashboard animates what the MCP server
inside Claude Code is doing in another process. Hover a node for details, click it for symbols,
dependencies, scars and impact analysis, and roll back snapshots from the side panel.
aether tui is the terminal version: KPIs, savings sparkline, live event bus, scars and snapshots,
with i (re-index), s (snapshot) and x (scan) key bindings.
Benchmark (this repository)
aether benchmark (or python benchmarks/run_benchmark.py) indexes the repo into a throwaway
database and runs 15 realistic queries. Results on a Windows 11 laptop, Python 3.12:
Metric | Value |
Graph | 36 files · 610 symbols · 2,915 edges |
Cold index / warm re-index | 876 ms / 70 ms |
Query latency | p50 33 ms · p95 48 ms (first query 455 ms builds the vector matrix) |
Tokens (raw files of the hits → AetherOS package) | 224,297 → 21,000 (90.6% saved) |
Input cost saved over the 15 queries | $0.41 on Sonnet 5.5 · $0.81 on Opus 5.5 |
"Raw" counts the full files an agent would otherwise open to see those hits, so the comparison is conservative for big repos and generous for tiny files. When a package would cost more than the raw files (tiny repos), the savings are reported as 0 rather than a negative number.
Swarm orchestration
aether swarm "Add a discount engine with per-customer rules"
# -> .aether/worktrees/<run>/{architect,builder,tester,security_auditor} + briefs/<role>.md
# work in each worktree with your agent (or pass --execute to use your own API key / Ollama)
aether swarm-verify <run> # merges role branches in an integration worktree, runs tests + secret scan
aether swarm-merge <run> # snapshot, then --no-ff merge into your branch
aether swarm-cleanup <run>With --execute, roles call the official Anthropic SDK (pip install "aether-os[llm]", reads
ANTHROPIC_API_KEY) or a local Ollama at http://localhost:11434. Tiers default to claude-haiku-5-5,
claude-sonnet-5-5 and claude-opus-5-5; override with AETHER_FAST_MODEL, AETHER_BALANCED_MODEL,
AETHER_ARCHITECT_MODEL and AETHER_OLLAMA_MODEL.
Plugins
Built-in: docker_inspector (compose services, ports, running containers), git_history_scars
(preventive scars from fix commits), env_shield (.env vs .env.example, leaked example values,
un-ignored env files; only variable names are stored). Project plugins go in .aether/plugins/*.py,
subclass plugins.base.BaseAetherPlugin, and are loaded only when listed in trusted_plugins in
.aether/config.json and they pass a static audit (no eval/exec/subprocess/sockets).
Security notes
The dashboard binds to
127.0.0.1, checks theHostheader, and requires a per-process token for every mutating endpoint. Foreign WebSocket origins are rejected.The vault that maps
<<AETHER_MASKED_SECRET_N>>back to values exists only in process memory..env, private keys and certificates are never indexed.Detection is heuristic. It's a safety net, not a replacement for a secrets manager or code review.
Supported languages
Python (native AST: classes, functions, methods, imports, calls, FastAPI/Flask routes with router
prefixes), TypeScript/JavaScript (functions, arrow functions, classes and methods, interfaces, imports,
Express and Next.js routes, fetch/axios calls), Go, Rust (actix/axum routes), JSON (package.json
dependencies and scripts), Dockerfile, Markdown sections, SQL tables, YAML/TOML/HTML/CSS/shell as
module nodes.
Development
See CONTRIBUTING.md, ARCHITECTURE.md and CLAUDE.md.
uv pip install --python .venv\Scripts\python.exe -e ".[dev]"
.\.venv\Scripts\python.exe -m pytestMIT licensed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Shared memory for coding agents. Stop re-explaining your codebase every session.
A shared, governed brain for AI agents: versioned context with approvals, local or hosted.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to query a locally indexed structural code graph — source entities, callers/callees, Git relationships and recorded mistakes — so they retrieve focused, token-bounded context instead of reading entire files. It runs over local SQLite and can be served through a CLI, agent hooks, an MCP executable and an authenticated local dashboard.24 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents and IDEs to query a local structural code graph and retrieve focused, token-bounded context on code entities, Git relationships, callers/callees, impact, paths, and recorded mistakes for more efficient sessions.24 npmMIT
- AlicenseNot gradedqualityAmaintenanceServes focused context to AI coding agents from a locally indexed structural code graph of entities, Git relationships and recorded project memory, so relevant code and past mistakes can be retrieved before reading whole files. Queries can also traverse relationships such as callers, callees, paths and impact through the CLI, hooks, MCP and a local authenticated dashboard.24 npmMIT
- AlicenseNot gradedqualityAmaintenanceServes focused, token-bounded context from a project-local SQLite structural code graph to AI coding agents, exposing indexed entities, Git relationships and recorded project memory for exploration, impact analysis and session continuity. Runs locally with a CLI, hooks, authenticated dashboard and optional plugin providers.24 npmMIT