• 

• 

• 

• 

• 

• 

• 

Agent Haderach

Inspiration

Coding agents are very good at reading code, searching a repository, and running tests. The problem is that most of what they learn disappears when the session ends.

One developer's agent may spend an hour finding the correct test command, understanding an architectural constraint, or proving that an intuitive approach does not work. A week later, another developer's agent encounters a related task and repeats the same investigation. Git preserves the final code, and files such as AGENTS.md preserve stable instructions, but neither captures the growing volume of granular experience produced while agents work.

We realized that agent context is reaching the same transition that application data once did: when information becomes large, dynamic, interconnected, and frequently queried, it should not live in an ever-growing pile of Markdown files. It needs infrastructure designed to make it structured, searchable, ranked, and reusable.

That inspired Agent Haderach: a shared repository intelligence layer through which every developer's agents can build on useful experience from the agents that came before them.

What it does

Agent Haderach connects coding agents to a repository-scoped experience service through MCP. During real development work, agents can preserve compact, evidence-backed records such as:

• workflows for building, testing, deploying, and debugging;
• lessons about architecture and code behavior;
• pitfalls describing failed approaches and why they failed;
• summaries and handoffs from completed or unfinished investigations;
• incidents affecting repository services;
• questions and verified answers associated with the work.

When a new agent begins a task, it searches Haderach before repeating broad investigation. The service filters and ranks the repository's accumulated experience, then returns a small set of high-signal summaries within a token budget. The agent expands only promising records, verifies them against the current repository revision, and reports whether they helped.

Haderach does not replace source search, Git history, or repository documentation. It complements them by preserving something they normally lose: how previous agents learned to change the code.

It also creates collaboration between humans. Developers approach problems differently and provide their agents with different expertise, tools, and instructions. Haderach makes the useful results of those different approaches available to everyone working on the repository—even across clean agent sessions and different developer accounts.

The web application makes this shared intelligence visible. Developers can create or discover repository workspaces, request access, manage MCP tokens, browse structured experience, inspect agent activity and reuse, and visualize how knowledge moves through the repository.

How we built it

Agent Haderach is a TypeScript monorepo with several deliberately separated layers:

• a Next.js web application for the product story and authenticated dashboard;
• a Hono service exposing REST endpoints and a remote Streamable HTTP MCP endpoint;
• an optional stdio MCP transport for local agent integrations;
• PostgreSQL persistence with Drizzle and SQL migrations;
• shared schemas and types used across the frontend, API, and MCP boundary;
• deterministic retrieval combining repository scope, metadata, lexical signals, evidence, confidence, freshness, and reuse feedback;
• compact-first retrieval, allowing agents to request full detail only for promising results.

The backend contains no LLM and makes no AI API calls. Connected coding agents perform the judgment: they decide what is worth preserving, generate structured summaries and retrieval terms, verify old information against current code, and report observed usefulness. This keeps the service model-agnostic.

We used Codex powered by GPT-5.6 throughout the project. Our development process was spec-driven: before implementing major subsystems, we drafted and repeatedly reviewed specifications for the architecture, experience store, MCP interface, authentication and workspace access, web UI, local workspace runtime, and evaluation methodology. Those documents became durable implementation contracts and acceptance criteria for Codex.

Codex also helped implement and test the application, diagnose integration failures, and operate the hosted environment through Railway's MCP server. Finally, Codex became a user of the product it helped build. We ran isolated agents in controlled repository worktrees, connected selected runs to Haderach through MCP, retained command and token telemetry, and evaluated their patches with tests that the solving agents could not see.

Challenges we ran into

The hardest product challenge was deciding what Haderach should be. A generic vector database or an agent chat application would add another layer without necessarily improving development. We focused instead on durable, granular experience with explicit evidence, revision metadata, progressive retrieval, and feedback from actual reuse.

Retrieval quality created a related challenge. Saving everything would overwhelm future agents and reproduce the context-window problem at database scale. We needed compact summaries, token budgets, repository isolation, ranking, freshness, confidence, and a way to demote stale or unsuccessful guidance.

Authentication and multi-user access also became more involved than the first local prototype. We added repository workspaces, owners and administrators, reader and writer roles, discoverable workspaces, access requests, and revocable personal MCP tokens without requiring someone to own the corresponding GitHub repository.

Deployment exposed differences between a local monorepo and two hosted services sharing PostgreSQL. We worked through service configuration, environment variables, proxying, authentication cookies, database migrations, and frontend error handling while keeping deployments deliberate rather than automatic.

The evaluation harness was another substantial challenge. Comparing two agents fairly requires more than timing them. We froze repository revisions and task prompts, sanitized snapshots to prevent solution leakage, isolated worktrees, retained telemetry, separated agent-authored tests from evaluator-owned hidden tests, and reviewed whether different patches were semantically equivalent. Kubernetes also required a pinned Go environment and a broader validation strategy because building a project of that size can fail for reasons unrelated to the candidate patch.

Accomplishments that we're proud of

We built a complete agent-to-agent experience loop rather than a static mockup. A real Codex process can retrieve experience through MCP, selectively expand it, apply it during repository work, and submit evidence-backed feedback that affects future ranking.

We are proud that Haderach connects developers as well as agents. It preserves the value generated by different engineering styles and agent setups without forcing everyone into the same conversation or workflow.

We also completed real-repository evaluations:

• In a p-limit feasibility test, a clean Codex agent received structured experience rather than another agent's patch or conversation. It produced the same correct runtime implementation, added an additional regression case, and recorded 45.6% fewer non-cached input tokens and 20.1% fewer total input tokens in that observed pair.
• In a larger Kubernetes allocator benchmark, both clean Codex and the target-informed Haderach condition passed evaluator-owned hidden tests and broader package tests. The target-informed run completed with 17.2% less wall time, 33.3% fewer commands, and 22.4% fewer total tokens than the clean run. This condition is an upper-bound demonstration based on highly specific prior experience, not a statistically general performance claim.

Beyond the core loop, we delivered a hosted multi-user product with repository workspaces, access control, personal MCP tokens, a responsive animated homepage, an experience dashboard, interaction visualizations, and a reproducible local workspace scaffold.

What we learned

We learned that the most useful unit of agent memory is not an entire conversation. It is a compact claim with provenance: what was learned, where it applies, what evidence supports it, which revision it came from, and whether later agents successfully reused it.

We also learned that retrieval alone is not reuse. An agent must verify the information against the current code and report an observed outcome before Haderach should strengthen that record. This feedback loop is essential because software knowledge becomes stale.

Our benchmarks reinforced the importance of context quality over context quantity. General related experience can create overhead if the agent must inspect and reject too much of it. Precise, task-relevant experience can substantially reduce exploration. The product therefore succeeds only if it finds the signal inside a continuously growing dataset—not simply because it stores more data.

Finally, we learned that agent collaboration is ultimately human collaboration. Every useful agent finding contains some part of the developer's intuition, constraints, and approach. Making that finding reusable allows the entire repository community to benefit from work that was previously trapped in one person's session.

What's next for Agent Haderach

Our immediate next step is to strengthen retrieval with PostgreSQL full-text search, hybrid semantic signals, better deduplication, contradiction detection, and task-aware ranking while preserving compact token budgets.

We want to ingest additional sources of development knowledge—including pull requests, commits, issue history, Slack discussions, and meeting notes—while preserving provenance and allowing teams to control what agents may access. These sources should become structured evidence, not an undifferentiated document dump.

We also plan to add trusted webhooks and automation so active agents can receive relevant updates quickly, plus background grooming that identifies stale, redundant, or contradicted experience. Future evaluations will use repeated and order-balanced trials across several large repositories to measure correctness, time, token use, and retrieval attribution more rigorously.

The longer-term vision extends beyond one repository. If an agent discovers that its task is blocked by a Kafka client, shared schema, or upstream service maintained elsewhere, Haderach could route an evidenced inquiry to that repository's workspace. Agents there could validate it, fix the source problem, or return repository-specific guidance. That would turn isolated coding agents into a network of shared engineering intelligence across repositories, teams, and organizations.

Built With

• agents
• mcp
• next.js
• postgresql
• rag
• typescript