Eggshell Review: Local Work Memory for AI Coding Agents

What Is Eggshell and How Does It Work?

Eggshell is AI memory for coding agents. It exists because independent chats do not share history: a second Codex session in the same repository starts from scratch even when the first session already searched the codebase, read the docs and answered the question.

Eggshell attaches to the agent through command hooks. As a chat runs, it journals the prompt, the tool operations and their terminal results, and the final verdict. A separate writer process persists this work to a local .egg work graph. At the start of a related turn, the AI memory searches that graph with lexical matching and MiniLM embeddings, then sends a compact handoff that lists Work and Outcome with an instruction to finish the remaining work. The agent decides what to reuse.

Setup is project-local: egg init creates a config and a .eggs directory that your repository ignores. The tool is written in Lean, runs fully on your machine, and makes no LLM calls to organize memory, which is why the project advertises cost savings rather than just convenience.

Key Features: Work Graph, Hooks & Handoffs

Eggshell's AI memory fits under four ideas: capture, organize, hand off and control.

• A local .egg work graph connects requests, outcomes and the operations that produced them
• Hooks capture prompts, tool results and final answers in Codex, with experimental project hooks for Claude Code, Gemini CLI, Cursor and OpenCode
• Relevant prior work is injected as a Work and Outcome handoff before a related turn acts
• Command controls such as !egg keep, drop, diff, graph, why and doctor give visibility into stored memory
• Profiles scope reading and writing by work, private or off modes
• No extra LLM calls are used to build or query the memory
• Written in Lean with 29 kernel-checked contracts and tests that make no network or LLM calls

Eggshell vs Native History, Memory Files and Prompting

A coding agent's built-in session history lives inside one conversation. Start a new chat and that context is gone unless you paste it in, which costs tokens and misses most of the actual work. Manually maintained memory files and prompting systems ask the model to summarize between sessions, again spending tokens and relying on the agent to stay consistent.

Eggshell's AI memory takes a different route: it captures the work from the non-agent side using hooks, organizes it locally with search and embeddings, and hands a compact summary to the next chat. The project's own experiments on a fixed source-code investigation workload report roughly 80 percent fewer tokens with equal or better answer quality, with a note that these numbers come from its own benchmark rather than a broad population study.

Pricing: Open Source and Free

Free and open source (Apache-2.0); local-only with no paid tiers, no hosted service, no telemetry and no account system

Best For

Recommended use cases and scenarios where Eggshell shines.

Frequently Asked Questions

Common questions about Eggshell, answered.