Source-linked AI summary
Ontology-Grounded Project Memory for Coding Agents
James Adam
TL;DR
Coding agents need project memory that preserves the types, currency, and relationships behind software decisions, not just nearby text. MOOSEDev provides ontology-grounded graph memory and outperforms vector retrieval on structural reasoning tasks while tying it on simple relevance.
Problem
Coding agents lack project memory that represents knowledge types, currency, and relationships such as supersession, leaving design rationale separate from source code.
Method
MOOSEDev stores typed architectural knowledge in an ontology-grounded graph and uses symbolic traversal, validation, and ranking to construct agent context.
Results
MOOSEDev was qualitatively better on completeness, absence, and supersession tasks, while retrieval precision was not the differentiator and simple relevance conditions tied.
Takeaways & Limitations
Ontology-grounded memory is most useful when coding-agent queries require complete sets, absence judgments, or relationship traversal rather than ordinary relevance retrieval.
Takeaways & Limitations
The capability depends on disciplined, correct capture, which adds friction, and MCP tool use depends on the agent deciding to call it.
Abstract
from arXiv · showhide
Coding agents have become the primary means of generating new code in many software projects, and the resulting velocity of changes makes keeping track of the reasons behind those changes challenging. This paper introduces MOOSEDev, a system designed to give coding agents structured, ontology-grounded project memory. The system captures architectural decisions, lessons, constraints, and rationales in a knowledge graph exposed to agents via a Model Context Protocol (MCP) interface. Records carry lifecycle status, provenance, and supersession links, queryable via MOOSE, a proprietary neurosymbolic engine that treats the symbolic layer as the primary reasoning substrate. We compared MOOSEDev against a production vector-memory tool on a neutral public corpus of 835 typed records. MOOSEDev returned the expected answer set essentially in full (0.98-1.00) on supersession, set-completeness, and negation questions, whereas the baseline's top-k retrieval surfaced between 6% and 27%. Conversely, relevance recall and token cost were largely equivalent between the two systems. We also describe a temporal commit-history bootstrap of our own codebase, a pre-registered live trial, and lessons learned.
1. Introduction
Coding agents increase the need to preserve architectural reasoning as teams face “comprehension debt” and must continually remind agents of design decisions. MOOSEDev treats agent memory as an ontology problem and presents a deployed neurosymbolic system with evaluation, workflows, lessons, and adoption analysis.
- Problem: Coding agents generate much of teams’ new code while human engineers retain architectural oversight, increasing the need to preserve design reasoning.The paper frames the resulting loss of understanding about why a codebase is structured as “comprehension debt.”
- Motivation: Agents need records typed as decisions, constraints, rationales, lessons, or anti-patterns, with lifecycle and supersession relationships that vector search does not represent.The motivation is that agents must distinguish current knowledge from historical records and understand how records relate.
- Contribution: MOOSEDev treats coding-agent memory as an ontology problem through a deployed neurosymbolic system evaluated against a production vector-memory tool.The paper also covers deployment workflows, lessons learned, and adoption barriers.
2. System: Typed Records on a Neurosymbolic Engine
MOOSEDev stores project knowledge as typed, ontology-grounded records in a knowledge graph, with validation, queryability, lifecycle, and provenance support. Its neurosymbolic engine performs symbolic retrieval and validation while consulting the LLM only at narrow, declared points, and exposes these capabilities through MCP tool groups.
- Typed records and ontologies: MOOSEDev records architectural decisions, lessons, constraints, rationales, and anti-patterns in a project knowledge graph grounded in softwareengineering and software-architecture ontologies.Both ontologies are OWL ontologies with companion SHACL shapes.
- Typed records and ontologies: Typed structure enables agent capture, SHACL validation, queries, lifecycle and provenance tracking, and alignment of new concepts.An example query is “accepted decisions with no recorded rationale.”
- Neurosymbolic reasoning: The neurosymbolic engine treats the LLM as an unreliable but useful sensor, while symbolic components handle matching, ontology traversal, evidence fusion, validation, and execution traces.The model is consulted only at narrow, declared points, allowing use of a small 8–32B model.
- Neurosymbolic reasoning: For current guidance, the engine traverses typed graph relationships, filters superseded records, and retrieves relevant project knowledge.This retrieval process is part of the engine’s agent-facing reasoning workflow.
- MCP interface: MOOSEDev exposes its capabilities over MCP through four tool groups: typed capture, reading, lifecycle, and integrity.Reading includes context retrieval, natural-language query, and SPARQL.
3. Evaluation: Structured vs Vector Memory
The evaluation compares ontology-grounded structured memory with no-memory, flat-file, and vector-memory conditions for coding agents. Structured memory shows a qualitative advantage on structural reasoning, while simple relevance retrieval remains broadly comparable.
- Test setup: The benchmark compares five memory and retrieval conditions, including no memory, flat documentation, mem0 vector memory, and ontology-grounded structured memory.B0 is the no-memory floor; B1-notes uses real documentation as flat files, while B1-mem0 ingests the same documentation with its native capture method.
- Evaluation protocol: Every run is an immutable transcript that can be re-graded without rerunning the agent.The evaluation also reports validation by reproducing the graph condition’s strict-match score.
- Capability differences: Structured memory outperforms vector memory on tasks requiring complete enumeration, absence claims, and relationship traversal.The advantage is not caused by incomplete ingestion: B1-mem0 contains the relevant facts, but ranked-slice retrieval limits structural reasoning.
- Parity on retrieval: 0.82 coverage is achieved by the graph on simple relevance at roughly 35k agent tokens, versus mem0’s 0.67–0.90 at roughly 40k.On retrieval tasks where vector memory is expected to excel, the conditions are described as tying overall.
4. Deployment, Bootstrap, and Lessons
This section describes history-based repository bootstrapping, a pre-registered live trial, and evaluation lessons, while identifying capture discipline and host-tool dependence as adoption barriers.
- Bootstrapping existing repositories: Commit-by-commit history extraction recovered seven real supersession chains from the authors’ repository.The workflow assigns historical timestamps to typed records, and domain-level ontologies require no project-specific schema work for new codebases.
- A pre-registered live trial: The pre-registered live trial tests structured memory during daily work on two production codebases.It uses sixteen fixed context-recovery reference points targeting reversals whose earlier approaches were deleted from the current tree.
- Lessons for practitioners: The evaluation nearly produced three wrong conclusions because of a grading artifact, a configuration failure, and a misleading commit message.These failures motivated rules concerning benchmark measurement and data quality, including an apparent 20-point win and a relevance loss caused by the memory server being down.
- Barriers to adoption: Correct capture is necessary for the capability advantage, but it adds friction and MCP passivity favors higher-tier models.Flat capture reduces the graph to free-text parity; the evaluation covered one agent family, GPT-5.x.
5. Conclusion
Ontology-grounded memory matches vector-memory retrieval where both are strong and is clearly better for completeness, absence, and supersession. The next step is integrating exact record capture and constraint-gated editing into coding-agent workflows.
- Comparative performance: Ontology-grounded memory matches a common vector-memory tool where retrieval is strong.This comparison assumes effective capture.
- Comparative performance: Ontology-grounded memory is clearly better on completeness, absence, and supersession.
- Next step: Small local models with limited context windows should benefit most from ontology-grounded memory.The proposed workflow pushes entity-exact records when code is touched and gates edits on recorded constraints.