[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"ri1X5A61Qo":3},"\u003Cp align=\"center\">\n  \u003Cpicture>\n    \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/brand/eggshell-primary-horizontal-white.svg\">\n    \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/brand/eggshell-primary-horizontal.svg\">\n    \u003Cimg src=\"docs/assets/brand/eggshell-primary-horizontal.svg\" alt=\"Eggshell\" width=\"420\">\n  \u003C/picture>\n\u003C/p>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>AI memory. Fewer tokens.\u003C/strong>\u003Cbr>\n  Reuse prior work across independent AI agent chats, with local memory and no LLM calls to organize it.\n\u003C/p>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https://github.com/momonpya/eggshell/actions/workflows/ci.yml\">\u003Cimg src=\"https://github.com/momonpya/eggshell/actions/workflows/ci.yml/badge.svg\" alt=\"CI\">\u003C/a>\n  \u003Ca href=\"lean-toolchain\">\u003Cimg src=\"https://img.shields.io/badge/Lean-4.33-111111\" alt=\"Lean 4.33\">\u003C/a>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https://img.shields.io/badge/license-Apache--2.0-111111\" alt=\"Apache-2.0 license\">\u003C/a>\n\u003C/p>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https://chatgpt.com/plugins/plugins_6aa482a5d9048191a727260b5f898078\">Get the plugin\u003C/a> ·\n  \u003Ca href=\"#install\">Install\u003C/a> ·\n  \u003Ca href=\"docs/try-it.md\">Try it yourself\u003C/a> ·\n  \u003Ca href=\"docs/cli-demo.md\">Watch the demo\u003C/a> ·\n  \u003Ca href=\"#how-it-works\">How it works\u003C/a> ·\n  \u003Ca href=\"#evidence\">Evidence\u003C/a> ·\n  \u003Ca href=\"#control-and-inspection\">Controls\u003C/a> ·\n  \u003Ca href=\"#privacy\">Privacy\u003C/a>\n\u003C/p>\n\nEggshell is **local memory that helps AI agents use fewer tokens**.\nIt saves work from one chat and makes relevant results available to a separate\nchat: repository searches, commands, documentation findings, and conclusions.\nIt is useful when you return to related work in the same project.\n\nIn our LLVM follow-up experiment, Eggshell used **about 80% fewer tokens than\nstarting fresh**, with **9 of 10 answers needing no substantive correction**.\nMemory is built and organized locally, **without LLM calls or additional billed\ntokens for memory management**. These results cover one task with existing\nprior work; see [Evidence](#evidence) for the comparison and its limits.\n\n**Same task. Two new chats. Compare token use — 30 seconds.**\n\n[![Looping Codex CLI demo: the same follow-up task in two new chats, without memory and with Eggshell. The recorded Eggshell follow-up used 81.8% fewer tokens.](docs/assets/demo/cli-demo-loop.gif)](docs/cli-demo.md)\n\nActual Codex CLI, Luna xhigh, independent ephemeral chats. In this recorded pair,\nEggshell used **81.8% fewer input + output tokens in the second chat**; both\nanswers passed static source review. One pair, with time edited for clarity.\n[Full-resolution video and measurement details](docs/cli-demo.md) ·\n[Try it in two chats](docs/try-it.md).\n\nUse the published **Codex plugin**, or the separate, experimental\n[adapters for Claude Code, Gemini CLI, Cursor, and OpenCode](adapters/README.md).\nThe adapters use the same memory engine and are built and installed separately.\nThey have automated engine integration tests; live agent sessions and token\nsavings have not yet been evaluated for those four clients.\n\n## Install\n\nFor **Claude Code, Gemini CLI, Cursor, or OpenCode**, follow the\n[adapter installation guide](adapters/README.md#install). The steps below install\nthe **Codex plugin**.\n\nYou need macOS or Linux on Apple Silicon/ARM64 or x86-64, Python 3, and the Codex\nCLI available as `codex`. Your Codex client must support plugins and command\nhooks. Setup downloads the Eggshell binary and a local search model.\n\n1. **[Install the plugin](https://chatgpt.com/plugins/plugins_6aa482a5d9048191a727260b5f898078)**,\n   then ask Codex: **“Set up Eggshell for this project.”** Setup installs the\n   runtime and search model and prepares the project, preserving existing settings.\n2. **Enable it in `/hooks`**, then start a new chat in the project.\n3. **Check the startup message:** “Eggshell session hook connected”. Run\n   **`!egg doctor`** to check setup. If the message is absent, check `/hooks`.\n   Complete the [two-chat example](docs/try-it.md) and use **`!egg graph`** to\n   confirm that saved work reaches the follow-up.\n\nAfter initial setup, recording and relevant handoffs are automatic; ordinary\ntasks need no special prompts. Missing setup produces a startup notice once the\nhooks are trusted. **This integration requires Codex command hooks; ordinary\nChatGPT Chat does not provide automatic Eggshell memory.**\n\n\u003Cdetails>\n\u003Csummary>Install from a terminal instead\u003C/summary>\n\n```sh\ncurl --proto '=https' --tlsv1.2 -fsSL \\\n  https://raw.githubusercontent.com/momonpya/eggshell/main/install.sh | sh\nexport PATH=\"${EGGSHELL_PREFIX:-$HOME/.local}/bin:$PATH\"\ncd your-project\negg init\n```\n\nThe installer checks the release checksum, installs the plugin and `egg`\ncommand, and prepares local search. Add the same PATH setting to your shell\nconfiguration if needed. In Codex, review and enable Eggshell's hooks through\n`/hooks`, then start a new chat in the project.\n\n\u003C/details>\n\n`egg init` creates `.eggshell.toml` and configures `.eggs/work.egg`, a local file\nof saved work and outcomes. The `.eggs` directory is ignored by Git. The work\nfile appears when the first turn is saved.\n\n### Try it in two chats\n\n**[Use the small public sample](docs/try-it.md)** for copyable task prompts,\nbaseline tests, and checkpoints for saved work and the delivered handoff.\nIt needs no private repository. To try Eggshell in your own project:\n\n1. In a Codex chat in the initialized project, ask a real investigation question,\n   such as “Find how configuration is loaded and identify the relevant tests.”\n2. Let Eggshell save tool results as the investigation progresses and the final\n   answer when the turn stops. `!egg keep` can explicitly flush the finished turn.\n3. Open a separate Codex chat in the same project and ask a related follow-up,\n   such as “Which tests should change if we add a new configuration option?”\n4. Run `!egg graph` to inspect the prior work that was actually sent to Codex.\n\nThe leading `!` runs an Eggshell control command in Codex without a model turn.\nIn a terminal, use `egg init` or `egg uninstall codex` without the `!`.\n\n**[Tell us how your first run went](https://github.com/momonpya/eggshell/issues/new?template=first-run.yml)**—\nwhether it worked or stopped at setup, saving, or delivery. A short report helps\nus improve the steps that get in your way.\n\nEggshell journals each tool result before searching for related work. A separate\nwriter saves those observations to `.egg` while the turn is still running; the\nfinal answer is saved when the turn stops. Interrupted writes remain queued and\nretry automatically. `!egg keep` can explicitly save a finished turn; `!egg drop`\nclears the active turn without removing saved observations or queued commits.\n\nFor shared work files, custom install locations, and troubleshooting, see the\n[Plugin guide](docs/codex-plugin.md).\n\n## How it works\n\n1. **Record work and outcomes.** The integration observes the current request,\n   supported tool inputs and results, and the final answer. A timeout or empty\n   result can be useful evidence too.\n2. **Select relevant history.** Local text matching and MiniLM embeddings find\n   related work in the files you allow Eggshell to read. The graph connects\n   requests to outcomes and their supporting operations.\n3. **Continue the task.** Eggshell sends selected prior work as a **handoff**:\n   context for the new chat. The agent is asked to reuse supported findings, check\n   open or changed facts, and report what it reused, checked, or left unverified.\n4. **Save progress.** Each observed tool result is saved independently. The final\n   answer adds the parent task result; unfinished work remains open.\n\nPast results remain historical evidence. A changed source file or condition may\nrequire a new check; an old success is not proof that today's task is complete.\nEggshell preserves the earlier outcome so the agent can explain what changed.\n\nSearch and graph processing run locally. Eggshell does not ask an LLM to write\nsummaries, classify memories, or maintain the graph. Selected memory and the\nagent's subsequent work still consume the model's normal input and output tokens.\nThe engine, adapters, retrieval selection, setup logic, and package builder are\nwritten in Lean. Python is confined to FastEmbed inference and the existing\nNumPy numerical kernels; it does not organize memory or select handoffs.\nSee [verified contracts and runtime boundaries](docs/lean-boundaries.md).\nSee the [architecture reference](docs/architecture.md) for matching, graph\noperations, and the Lean core.\n\n## Control and inspection\n\nRun these inside the relevant Codex chat:\n\n```text\n!egg                  show active settings and staged turn\n!egg keep             save the staged turn now\n!egg drop             clear the active turn (saved work is retained)\n!egg diff             preview what would be saved\n!egg graph            show the exact handoff sent to Codex\n!egg why              explain the handoff selection\n!egg inspect          show resolved storage paths\n!egg doctor           check setup without changing settings or memory\n!egg off              disable memory and clear the active turn (saved work is retained)\n!egg on               enable memory again\n!egg next private     read memory without saving the next turn\n!egg next off         disable memory for the next turn\n```\n\nProfiles specify which work files can be read and where new work is saved.\nThe default `work` profile reads and writes the project's work file. `private`\nis read-only; it still sends relevant saved work to Codex. `off` disables both\nrecording and handoffs. [More controls and configuration](docs/codex-plugin.md).\n\n## Evidence\n\n### One LLVM follow-up task, ten completed trials\n\nUsing Codex, we repeated one investigation of Clang target and language options\nthat affect toolchain selection or forwarded arguments. Each trial started in an independent\nchat with the same question, source snapshot, model, and prior `.egg`. These\ntrials used the **current default handoff prompt**.\nIt directs the agent to reuse supported results, check unresolved or changed\nfacts, and report what was reused, checked, or left unverified.\n\nTokens are model input plus output; reasoning tokens are already included in\noutput. The figures below measure follow-up work using previously saved work.\n\n| Measurement | Tokens per completed trial | Reduction vs. fresh reference |\n| --- | ---: | ---: |\n| Fresh reference: one run, no prior memory | 5,355,282 | — |\n| Eggshell: arithmetic mean of 10 completed trials | **683,362** | **87.2%** |\n| Eggshell: all 12 attempts, divided by 10 completions | **962,207** | **82.0%** |\n\nThe ten completed trials used 6,833,615 tokens in total, ranging from 140,781 to\n1,803,931 per trial. Two additional attempts failed because a hook output was\nmissing; they consumed 2,788,458 tokens. Including those attempts gives a total\nof **9,622,073 tokens** to obtain ten completed trials. Means are rounded to the\nnearest token; percentages use the unrounded values.\n\n**Quality:** a review of the answers against the fixed source and execution\nrecords found six usable answers, three needing minor corrections, and one\nneeding a substantive correction to its cause and reproduction explanation.\nThus **9 of 10 needed no substantive correction**. This was a single-reviewer,\nnon-blinded assessment, not a 90% accuracy estimate. Clang Driver runtime tests\nwere unavailable, so the review assessed static evidence and reporting rather\nthan dynamically verified behavior.\n\nThis is one task repeated ten times, compared with a single fresh reference.\nIt does not establish a general reduction rate, quality equivalence to fresh,\nor superiority over other memory methods.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Workload, prior-work cost, and measurement record\u003C/strong>\u003C/summary>\n\n- Investigation: Clang toolchain selection and argument forwarding, answered in\n  Japanese.\n- LLVM source commit: `6dfe1677ab8dffbc6ec13d53a1e0215d75147689`.\n- Model: `gpt-5.6-luna`, reasoning effort `xhigh`; trials ran serially.\n- Prior work: the same 840,048-byte `.egg` from the preceding investigation, restored\n  before each trial. It fixes the prior work, not the model's randomness.\n- The preceding investigation used **6,552,155 tokens**, recorded separately and\n  excluded from the follow-up figures above. The percentages describe reuse of\n  existing work, not the cost of starting a new investigation from scratch.\n- Per-trial counts, answer and receipt hashes, prompt text, and review outcomes\n  are in the [measurement record](docs/benchmarks/llvm-follow-up.json).\n\n\u003C/details>\n\n## Privacy\n\nEggshell has no hosted service, telemetry, or account system. Saved work,\nembeddings, and search processing stay on your machine. **Selected prior work\nis passed to your agent as model input** and is handled under the settings and\nterms of its model provider, just like other context in the chat.\n\nInstallation downloads the release, Python dependencies, and MiniLM model.\nWork files may contain prompts, source code, and tool results; choose carefully\nwhich files a project can read. Read-only mode prevents saving new work but\ndoes not prevent sending existing memory to the agent.\n\nSee [PRIVACY.md](PRIVACY.md) for storage locations, network behavior, and\nremoval. Report vulnerabilities through the private channel in\n[SECURITY.md](SECURITY.md).\n\n## Development\n\nSource builds use the toolchain pinned in [`lean-toolchain`](lean-toolchain).\n\n```sh\nlake build eggshell eggshell_tests\nEGGSHELL_DATA_ROOT=\"$PWD/.lake/eggshell-tests-data\" \\\n  .lake/build/bin/eggshell_tests\n```\n\nTo install a source build:\n\n```sh\nlake build eggshell\nEGGSHELL_PREFIX=/absolute/install/root \\\n  .lake/build/bin/eggshell install codex\nexport PATH=\"/absolute/install/root/bin:$PATH\"\negg init\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) before changing the persistent graph or\nmaking performance claims. Brand assets are documented in\n[docs/brand.md](docs/brand.md).\n\nEggshell is pre-release software. Persisted data created by an incompatible\ndevelopment checkout may be rejected rather than silently reinterpreted.\n\n## License\n\nLicensed under [Apache-2.0](LICENSE).\n",1789317489750]