Eggshell

Product Introduction

1. Definition: Eggshell is a local memory engine and AI agent integration framework. Technically, it is a Lean-language application that provides persistent, searchable memory for AI-assisted development workflows, enabling context retention across independent chat sessions without relying on the LLM for memory management.
2. Core Value Proposition: It exists to drastically reduce token consumption and eliminate repeated investigation work in AI-powered coding. By storing tool results, code searches, and conclusions locally, it allows subsequent AI agent chats to reuse prior work efficiently, leading to faster iterations and lower API costs.

Main Features

1. Local, LLM-Free Memory Organization: Eggshell's core engine is written in Lean and runs entirely on the user's machine. It observes and journals tool inputs, outputs, and final answers from an AI agent's session. This data is structured into a searchable graph without making any additional LLM API calls, ensuring privacy and zero token cost for memory management.
2. Semantic and Text-Based Retrieval: The system uses a hybrid retrieval approach. It employs FastEmbed with a MiniLM model for semantic similarity searches and traditional text matching to find relevant prior work stored in the local .egg file. This dual-method ensures high-recall retrieval of related code investigations, command outputs, and documentation findings.
3. Automated Handoff Delivery: When a new, related task is initiated in a separate chat, Eggshell automatically constructs and injects a handoff context. This handoff presents the relevant prior work (requests, supporting evidence, and outcomes) to the new AI agent instance, instructing it to reuse verified findings, check changed facts, and report on what was leveraged.
4. Cross-Client Adapter Architecture: While featuring a dedicated ChatGPT Codex plugin, Eggshell provides a modular adapter system for other AI coding assistants. Experimental adapters exist for Claude Code, Gemini CLI, Cursor, and OpenCode, all connecting to the same core Lean memory engine, demonstrating its platform-agnostic design philosophy.

Problems Solved

1. Pain Point: Context Amnesia in AI Chats. Traditional AI coding assistants operate in ephemeral sessions, forcing developers to re-explain project context, re-run searches, and re-investigate codebases in every new chat, leading to high token waste and productivity loss.
2. Target Audience: Software Engineers and Developers working on complex, long-term projects with AI assistants; Tech Leads managing AI-assisted code reviews and architectural investigations; Research Engineers using AI for exploratory coding and documentation.
3. Use Cases: Onboarding to a New Codebase: An AI agent can leverage past investigations about build configuration and key modules. Iterative Debugging: Follow-up chats on a bug can immediately access prior stack traces, hypothesis tests, and ruled-out causes. Cross-Feature Development: Work on a new API endpoint can reuse findings from prior chats about authentication middleware and database models.

Unique Advantages

1. Differentiation: Unlike cloud-based memory services or prompting techniques that use the LLM to summarize history, Eggshell is fully local and does not consume tokens for memory organization. It contrasts with simple chat history by providing structured, searchable evidence (tool results) rather than just conversational text, enabling precise, evidence-based handoffs.
2. Key Innovation: The verifiable, Lean-based core engine. The critical logic for graph operations, retrieval selection, and handoff construction is implemented in Lean, a language for writing verifiable software. This provides a high-assurance foundation for the memory system's correctness, separating it from the Python-based embedding inference layer and ensuring reliable, deterministic memory management.

Frequently Asked Questions (FAQ)

1. How does Eggshell save money on AI API costs? By storing and retrieving work locally, it reduces the amount of context and repeated investigation that needs to be processed by the LLM in follow-up tasks. The provided evidence shows it can reduce token usage by over 80% for related tasks, directly lowering API consumption.
2. Is my code data sent to the cloud when using Eggshell? No. Eggshell operates entirely locally. The memory engine, search indexing, and handoff generation run on your machine. Only the final, curated handoff context is sent to the AI provider (e.g., OpenAI), just as you would manually paste relevant code snippets.
3. Can I use Eggshell with GitHub Copilot or VS Code IntelliSense? Eggshell is designed for multi-turn investigative and task-oriented chats with AI agents, not for single-line code completion. It is compatible with assistants like ChatGPT Codex, Claude Code, and Cursor that support extended conversational context and tool use, not primarily completion engines.
4. What happens if the underlying code changes after work is saved? Eggshell treats saved work as historical evidence. The handoff prompt explicitly instructs the AI agent to check for changed facts or source files. The system preserves the old outcome so the agent can explain what has changed, preventing blind reuse of stale information.
5. How do I install the Eggshell plugin for ChatGPT Codex? Installation is managed via the Codex CLI. You can either use the one-click plugin installer from the ChatGPT plugin store or run the terminal installer script (curl ... | sh), then run egg init in your project and enable the hooks within the Codex interface.