Vertex Palace

An open-source memory and context router that gives Codex a task-specific map, scoped project memory, execution boundaries, and auditable evidence instead of another full-repository scan.

Comment

Inspiration

As my projects grew larger, a single coding issue could keep an AI agent working for more than an hour and consume an unreasonable number of tokens. The agent would repeatedly search the same repository, reopen files, lose earlier architectural decisions, and sometimes repeat mistakes that had already been solved.

After I gained access to Codex, I used it intensively and became convinced that the problem was not only model capability. The model needed a better way to enter and navigate a large codebase.

My visual inspiration came from transforming two-dimensional information into a three-dimensional mental structure. That led me to architecture and then to the human memory-palace technique: floors, rooms, cabinets, drawers, routes, and warning signs.

Instead of giving an AI agent more context, I wanted to give it the right context at the right time.

What it does

Vertex Palace is a local memory and context router for Codex and other coding agents.

It maps a repository into a structured palace containing floors, rooms, drawers, symbols, dependencies, tests, routes, project memories, and a Pitfall Board. Before starting a task, the agent can make one context request and receive a bounded, task-specific route instead of immediately scanning the entire repository.

Vertex Palace can:

  • Scan TypeScript, JavaScript, Python, Markdown, JSON, and fallback file formats.
  • Index symbols, imports, dependencies, tests, directories, hashes, and architectural relationships.
  • Classify a task and select an adaptive operating mode.
  • Separate context into Primary, Support, Deferred, and Excluded evidence.
  • Preserve project decisions and previous mistakes as scoped memory.
  • Add explicit execution boundaries, required evidence, stop conditions, and warnings.
  • Evaluate the files changed after a task and report route coverage or possible overconfidence.
  • Run through a CLI, an MCP server, or a Codex plugin.

The adaptive router can choose between bypass, route-lite, full-palace, and guarded-memory-palace modes. Small local tasks do not need to pay the same routing cost as cross-stack work or tasks that depend on historical decisions.

Vertex Palace is not simply a vector-search RAG system. RAG usually retrieves semantically similar chunks. Vertex Palace combines deterministic repository structure, task intent, dependency and test relationships, scoped memory, explicit exclusions, and post-task evaluation.

Everything is local by default. It does not require an API key, upload source code, or depend on a remote vector database.

How we built it

Vertex Palace is an open-source TypeScript and Node.js monorepo with a scanner, parsers, structural indexes, an adaptive route planner, context packer, memory system, evaluator, CLI, MCP server, Codex plugin, fixture repositories, and automated tests.

The project existed as an early v0.1.4 prototype before Build Week. During Build Week, I used Codex with GPT-5.6 as my primary engineering partner to turn that prototype into an adaptive and measurable system.

Codex helped me inspect the existing architecture, implement routing contracts, add memory safeguards, create telemetry, reproduce failures, build controlled benchmarks, test real open-source repositories, maintain documentation, and prepare the public demonstration.

The stable public npm package is v0.2.3. The repository currently contains a v0.3.0 source release candidate with the latest adaptive routing and evaluation work. I am deliberately not publishing that candidate to npm until its research and release gates are complete.

Challenges we ran into

The hardest challenge was discovering that the original assumption was incomplete.

A smaller context route does not automatically mean lower end-to-end token usage or faster execution. The route planner itself performs work, and an agent can still over-read, re-search, or reason for longer after receiving a smaller route.

In the first completed controlled study, Full Palace was correct and safe, but compared with Control it used a paired median of 67,223.5 additional reported tokens, 8.5 additional tool calls, and 29.8 additional seconds.

Some experimental attempts also failed for methodological reasons. One was invalidated by PowerShell interpolation, and another was stopped because Windows split writable roots made patch verification unreliable. I kept these failures in the public research history rather than removing them.

The adaptive v2.2 study completed 64 valid arm executions. Adaptive routing reduced Palace-generated context compared with Full Palace, but it did not prove an end-to-end efficiency advantage over Control. It also missed useful seeded memory in all four relevant trials.

Real open-source validation found another important issue: package-level architectural files can be relevant even when they are absent from the final code diff. This showed that route evaluation needs both strict diff precision and architecture-aware accepted precision.

Accomplishments that we're proud of

The most important accomplishment is not a favorable benchmark. It is building a system that can measure and expose its own weaknesses.

Across the completed v1 and v2.2 studies, we recorded 124 valid and correct arm executions. The results are published even when they do not support the original performance hypothesis.

The current engineering gates include:

  • 90 passing workspace tests at the latest product gate.
  • CI coverage on Windows, macOS, and Ubuntu with Node.js 20 and 24.
  • npm packaging, lint, MCP smoke, and dry-run publication checks.
  • Exact routing gates on the Zod TypeScript monorepo and the Requests Python repository.
  • A public p-limit case study that preserves both focused test success and an unrelated upstream test failure.
  • A reproducible benchmark repository containing protocols, raw artifacts, analysis, limitations, and stopped experiments.

Vertex Palace now provides a working CLI, MCP integration, Codex plugin, adaptive task modes, scoped memory, route evaluation, and a transparent research trail.

What we learned

The research changed how I describe Vertex Palace.

It has not yet proven that it always saves tokens or makes Codex faster. Its strongest demonstrated value today is structured repository routing, historical decision preservation, prevention of repeated mistakes, client and tenant guardrails, and auditable task context.

I also learned that confidence is not evidence. A route can report high confidence and still omit a front-end dependency, a shared stylesheet, or a useful project memory. Confidence must therefore be tied to task-intent coverage, required evidence, exclusions, and the files actually changed.

Memory must be scoped and freshness-aware. Useful memory can prevent an expensive repeated mistake, while stale or unrelated memory can increase cost and mislead the agent.

The most important benchmark is now Adaptive versus Control. Full Palace remains useful as a diagnostic reference, but it is no longer the default answer for every task.

What's next for Vertex Palace

The next research stage uses a frozen v3 protocol and real agent tasks.

The priorities are:

  • Complete the formal Adaptive versus Control study.
  • Improve memory recall without allowing stale memory to dominate.
  • Strengthen cross-stack, tenant, and task-intent recognition.
  • Add better stop conditions and context ceilings.
  • Automate incremental index freshness.
  • Expand evaluation on real TypeScript and Python repositories.
  • Separate routing quality, task correctness, token usage, time, and tool-call overhead.
  • Publish v0.3.0 only after the release candidate passes its engineering and research gates.

My goal is not to prove that Vertex Palace wins every benchmark. My goal is to build an honest, inspectable context layer that helps coding agents enter large projects with the right map, the right history, and clear boundaries.

Try it

Install the stable CLI:

npm install -g vertex-palace@0.2.3

Inside any Git repository:

palace context "fix the checkout shipping bug" --auto --budget 6000

After making changes:

palace evaluate "fix the checkout shipping bug" --changed-file frontend/app/checkout/page.tsx --changed-file backend/src/shipping/quote.service.ts

Install the Codex plugin:

codex plugin marketplace add lohchanhin/vertex-palace --ref v0.2.3

Vertex Palace supports Windows, macOS, and Linux with Node.js 20 or newer.

Built With

Share this project:

Updates