Never lose the thread.

You run an agent inside Elpis, and it becomes Elpis.

More QUALITY. More QUANTITY.

Install • Features • Docs

Quickstart

Linux x86_64 and macOS on Apple Silicon:

curl -fsSL https://raw.githubusercontent.com/MasihMoafi/Elpis/main/scripts/install-elpis.sh | bash && ~/.local/bin/elpis

The installer picks the right binary for your machine and also installs RTK, which powers shell-output filtering. On first launch, choose a provider and sign in or enter its API key.

v0.1.1 is the latest published release. The redesigned /prune and automatic pressure policy described below are implemented on main but still await Masih's functional acceptance before the next release.

Related MCP server: MCP Agent Memory

What is Elpis

You run an agent inside Elpis, and it becomes Elpis.

The agent runs the model loop. Elpis owns everything around it: context, memory, continuity, retrieval, permissions, and provider choice.

Swap the agent and it inherits the same environment. Nothing about your project has to be explained twice.

Different paths. Same roots. One shared project.

Why Elpis

Long sessions fill up with transcripts, file reads, searches, and dead ends. Agents consume massive token budgets and execute dense sequences of tool calls to gather context—most of which is redundant and unnecessary. What matters gets buried in the story of how the agent got there, and every request pays for it.

Elpis keeps the two apart. The next request gets a small working set you can inspect. The full record stays on disk and is fetched only when it is needed.

The screenshots below are historical examples of the same prompt in Elpis and Codex. The original per-run records were not preserved.

A pinned, synthetic 3×10 comparison for exact recall, paraphrased recall, and negative controls is specified in docs/evals/context-continuity. It has a deterministic scorer, but no score is published because the required provider runs and raw transcripts have not been produced.

Start:

Example end state — Elpis:

Example end state — Codex:

Core Features

Context control in four layers

/prune runs Ace selectively on demand while keeping the conversation intact. /compact replaces the conversation with a full summary and starts a new context window.

Context Ledger

Tab — or Alt+C while a turn is running — opens a side panel listing every source admitted into the working set, each with its size and whether it is included. Toggling a row changes what the next turn actually receives, so context selection becomes an intentional operation instead of a side effect.

Where the window went

/context answers a different question: not what is admitted, but what filled the window. It shows usage as a grid broken down by category — user messages, agent responses, tool calls, system prompt, skills, free space — alongside the backtrack checkpoints you can jump to.

Session continuity

Goal and checkpoint state survive compaction, model switches, and restarts, so work resumes without replaying the transcript. Exact conversations, terminal events, and artifacts remain on disk as durable evidence.

Memory with provenance

Reusable memory is designed to be selective, size-capped, and attributable. It ships off, matching upstream Codex. Extraction works, but durable promotion has not produced a real MEMORY.md commit on Masih's install because the current recall threshold is not reached in normal use. /memories controls recall and writing independently; no claim that durable memory works is accepted without a promotion commit in the memories repository. See the measured state and eval.

MCP integrations you plug in

Elpis ships no retrieval or speech engine and downloads no models. MCP servers keep optional capabilities in their own processes, with their own dependencies and disk costs; /mcp confirms the servers you register are connected.

• Workspace retrieval: rag-mcp provides local semantic search over your own documents. Its embeddings, vector store, reranker, and any API key remain yours. See docs/rag.md.

• Voice transcription: Voice Commander records speech, transcribes it locally, and pastes at the active cursor. It remains an external companion; it can expose transcription as an MCP tool rather than adding Whisper, CUDA, Python, or model downloads to Elpis.

Privacy and ownership

No analytics are uploaded, and every OpenTelemetry exporter defaults to off — telemetry is sent only if you configure an exporter yourself. Bring your own keys: use OpenAI, Anthropic, Gemini, or OpenRouter without one provider being silently routed through another. Durable state is plain files you can inspect, edit, export, or delete.

Future development

• Windows support.

• Structured clarification and acceptance checks before difficult work.

• /auto model routing after it proves a real cost benefit.

• Voice input and LSP-backed code intelligence.

Documentation

• Context and pruning — the four context-control layers and the Context Ledger

• Sessions and continuity — exact resume, lean continuation, GOAL.md / ES.md

• Memory — the two-stage pipeline, the archive, and what you control

• Evals — source data, reproducible scorers, and publication gates

• Providers — every supported route, including local inference

• Workspace retrieval — how to plug in semantic search over your own documents

• Technical guide — product vision and architecture

License

Apache-2.0.

The execution foundation — terminal UI, patches, permissions, sandboxing, sessions — derives from OpenAI's Apache-2.0 Codex CLI. Elpis adds the context, continuity, memory, retrieval, and provider-control layer around it. Codex-derived source retains its upstream notices under codex-rs/.