AI memory. Fewer tokens.
Reuse prior work across independent AI agent chats, with local memory and no LLM calls to organize it.

Get the plugin · Install · Try it yourself · Watch the demo · How it works · Evidence · Controls · Privacy

Eggshell is local memory that helps AI agents use fewer tokens. It saves work from one chat and makes relevant results available to a separate chat: repository searches, commands, documentation findings, and conclusions. It is useful when you return to related work in the same project.

In our LLVM follow-up experiment, Eggshell used about 80% fewer tokens than starting fresh, with 9 of 10 answers needing no substantive correction. Memory is built and organized locally, without LLM calls or additional billed tokens for memory management. These results cover one task with existing prior work; see Evidence for the comparison and its limits.

Same task. Two new chats. Compare token use — 30 seconds.

Actual Codex CLI, Luna xhigh, independent ephemeral chats. In this recorded pair, Eggshell used 81.8% fewer input + output tokens in the second chat; both answers passed static source review. One pair, with time edited for clarity. Full-resolution video and measurement details · Try it in two chats.

Use the published Codex plugin, or the separate, experimental adapters for Claude Code, Gemini CLI, Cursor, and OpenCode. The adapters use the same memory engine and are built and installed separately. They have automated engine integration tests; live agent sessions and token savings have not yet been evaluated for those four clients.

Install

For Claude Code, Gemini CLI, Cursor, or OpenCode, follow the adapter installation guide. The steps below install the Codex plugin.

You need macOS or Linux on Apple Silicon/ARM64 or x86-64, Python 3, and the Codex CLI available as codex. Your Codex client must support plugins and command hooks. Setup downloads the Eggshell binary and a local search model.

1. Install the plugin, then ask Codex: “Set up Eggshell for this project.” Setup installs the runtime and search model and prepares the project, preserving existing settings.
2. Enable it in /hooks, then start a new chat in the project.
3. Check the startup message: “Eggshell session hook connected”. Run !egg doctor to check setup. If the message is absent, check /hooks. Complete the two-chat example and use !egg graph to confirm that saved work reaches the follow-up.

After initial setup, recording and relevant handoffs are automatic; ordinary tasks need no special prompts. Missing setup produces a startup notice once the hooks are trusted. This integration requires Codex command hooks; ordinary ChatGPT Chat does not provide automatic Eggshell memory.

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/momonpya/eggshell/main/install.sh | sh
export PATH="${EGGSHELL_PREFIX:-$HOME/.local}/bin:$PATH"
cd your-project
egg init

egg init creates .eggshell.toml and configures .eggs/work.egg, a local file of saved work and outcomes. The .eggs directory is ignored by Git. The work file appears when the first turn is saved.

Try it in two chats

Use the small public sample for copyable task prompts, baseline tests, and checkpoints for saved work and the delivered handoff. It needs no private repository. To try Eggshell in your own project:

1. In a Codex chat in the initialized project, ask a real investigation question, such as “Find how configuration is loaded and identify the relevant tests.”
2. Let Eggshell save tool results as the investigation progresses and the final answer when the turn stops. !egg keep can explicitly flush the finished turn.
3. Open a separate Codex chat in the same project and ask a related follow-up, such as “Which tests should change if we add a new configuration option?”
4. Run !egg graph to inspect the prior work that was actually sent to Codex.

The leading ! runs an Eggshell control command in Codex without a model turn. In a terminal, use egg init or egg uninstall codex without the !.

Tell us how your first run went— whether it worked or stopped at setup, saving, or delivery. A short report helps us improve the steps that get in your way.

Eggshell journals each tool result before searching for related work. A separate writer saves those observations to .egg while the turn is still running; the final answer is saved when the turn stops. Interrupted writes remain queued and retry automatically. !egg keep can explicitly save a finished turn; !egg drop clears the active turn without removing saved observations or queued commits.

For shared work files, custom install locations, and troubleshooting, see the Plugin guide.

How it works

1. Record work and outcomes. The integration observes the current request, supported tool inputs and results, and the final answer. A timeout or empty result can be useful evidence too.
2. Select relevant history. Local text matching and MiniLM embeddings find related work in the files you allow Eggshell to read. The graph connects requests to outcomes and their supporting operations.
3. Continue the task. Eggshell sends selected prior work as a handoff: context for the new chat. The agent is asked to reuse supported findings, check open or changed facts, and report what it reused, checked, or left unverified.
4. Save progress. Each observed tool result is saved independently. The final answer adds the parent task result; unfinished work remains open.

Past results remain historical evidence. A changed source file or condition may require a new check; an old success is not proof that today's task is complete. Eggshell preserves the earlier outcome so the agent can explain what changed.

Search and graph processing run locally. Eggshell does not ask an LLM to write summaries, classify memories, or maintain the graph. Selected memory and the agent's subsequent work still consume the model's normal input and output tokens. The engine, adapters, retrieval selection, setup logic, and package builder are written in Lean. Python is confined to FastEmbed inference and the existing NumPy numerical kernels; it does not organize memory or select handoffs. See verified contracts and runtime boundaries. See the architecture reference for matching, graph operations, and the Lean core.

Control and inspection

Run these inside the relevant Codex chat:

!egg                  show active settings and staged turn
!egg keep             save the staged turn now
!egg drop             clear the active turn (saved work is retained)
!egg diff             preview what would be saved
!egg graph            show the exact handoff sent to Codex
!egg why              explain the handoff selection
!egg inspect          show resolved storage paths
!egg doctor           check setup without changing settings or memory
!egg off              disable memory and clear the active turn (saved work is retained)
!egg on               enable memory again
!egg next private     read memory without saving the next turn
!egg next off         disable memory for the next turn

Profiles specify which work files can be read and where new work is saved. The default work profile reads and writes the project's work file. private is read-only; it still sends relevant saved work to Codex. off disables both recording and handoffs. More controls and configuration.

Evidence

One LLVM follow-up task, ten completed trials

Using Codex, we repeated one investigation of Clang target and language options that affect toolchain selection or forwarded arguments. Each trial started in an independent chat with the same question, source snapshot, model, and prior .egg. These trials used the current default handoff prompt. It directs the agent to reuse supported results, check unresolved or changed facts, and report what was reused, checked, or left unverified.

Tokens are model input plus output; reasoning tokens are already included in output. The figures below measure follow-up work using previously saved work.

The ten completed trials used 6,833,615 tokens in total, ranging from 140,781 to 1,803,931 per trial. Two additional attempts failed because a hook output was missing; they consumed 2,788,458 tokens. Including those attempts gives a total of 9,622,073 tokens to obtain ten completed trials. Means are rounded to the nearest token; percentages use the unrounded values.

Quality: a review of the answers against the fixed source and execution records found six usable answers, three needing minor corrections, and one needing a substantive correction to its cause and reproduction explanation. Thus 9 of 10 needed no substantive correction. This was a single-reviewer, non-blinded assessment, not a 90% accuracy estimate. Clang Driver runtime tests were unavailable, so the review assessed static evidence and reporting rather than dynamically verified behavior.

This is one task repeated ten times, compared with a single fresh reference. It does not establish a general reduction rate, quality equivalence to fresh, or superiority over other memory methods.

Privacy

Eggshell has no hosted service, telemetry, or account system. Saved work, embeddings, and search processing stay on your machine. Selected prior work is passed to your agent as model input and is handled under the settings and terms of its model provider, just like other context in the chat.

Installation downloads the release, Python dependencies, and MiniLM model. Work files may contain prompts, source code, and tool results; choose carefully which files a project can read. Read-only mode prevents saving new work but does not prevent sending existing memory to the agent.

See PRIVACY.md for storage locations, network behavior, and removal. Report vulnerabilities through the private channel in SECURITY.md.

Development

Source builds use the toolchain pinned in lean-toolchain.

lake build eggshell eggshell_tests
EGGSHELL_DATA_ROOT="$PWD/.lake/eggshell-tests-data" \
  .lake/build/bin/eggshell_tests

To install a source build:

lake build eggshell
EGGSHELL_PREFIX=/absolute/install/root \
  .lake/build/bin/eggshell install codex
export PATH="/absolute/install/root/bin:$PATH"
egg init

See CONTRIBUTING.md before changing the persistent graph or making performance claims. Brand assets are documented in docs/brand.md.

Eggshell is pre-release software. Persisted data created by an incompatible development checkout may be rejected rather than silently reinterpreted.

License

Licensed under Apache-2.0.