Nexus

Overview

Nexus is an active alpha research project investigating whether an AI engineering assistant can maintain a durable, trustworthy model of a software project across sessions. Conventional assistants rely on transient conversation history, causing them to lose context regarding architectural constraints or prior task outcomes. Nexus addresses this by building persistent, grounded memory from project state, git history, and verified runtime observations.

Research Motivation

The core hypothesis is that long-lived AI assistance requires four simultaneous properties: provenance-aware memory, grounded context assembly, decoupled subsystem boundaries, and a universal safety boundary. Nexus tests if autonomy can be safely scaled by extending a central capability gate, rather than granting models unrestricted access to the user's environment.

Architecture

Nexus is a Python 3.13 monorepo using FastAPI as the composition root. Leaf services are isolated via structural protocols, preventing direct dependency on API or database implementations. The system flow processes requests through a context assembler, a provider-neutral model router, and a governed tool loop that includes policy checks, confirmation steps, and checkpointing.

CLI / REST request -> FastAPI -> ContextAssembler -> ModelRouter -> ToolLoop (policy/checkpoint/execution) -> Observation Ledger

Current Capabilities

• End-to-end project lifecycle: initialization, scanning, planning, and task persistence.
• Provider-neutral model routing supporting Anthropic, Ollama, and null fallback.
• Uniform tool execution lifecycle: schema validation, capability checks, and audit-ledger logging.
• Cognitive memory pipeline that promotes significant observations to persistent storage.
• Shadow-git checkpoints that enable repository rollback.

Engineering Challenges and Lessons

The project has identified that truth in agent systems requires strict lifecycle awareness. Memory formation must account for rollback semantics; recording a successful mutation before confirming it survives a rollback creates false beliefs. Furthermore, human confirmation is only effective when tied to a recomputed effect preview, preventing drift between what the user approves and what the agent executes.

Current Limitations

• In-progress state: The Sprint 15 branch contains uncommitted work and is not a clean release snapshot.
• Blocking I/O: Git and ripgrep subprocesses currently block within async runtime paths.
• Incomplete implementation: General write_file and run_command bodies remain deferred pending safety validation.
• Process-local caching: The context cache is not suitable for multi-worker deployments.

Future Work

The roadmap focuses on completing the Personal Intelligence module, implementing bounded parallel read execution, and finalizing the safety review for mutation tools. Future sprints will introduce a Conscience Engine for reasoned policy evaluation and transition the process-local cache to Redis.

Graduation Criteria

Success for Nexus is defined by the ability to maintain a reliable, tamper-evident audit ledger of autonomous actions that can survive multiple sessions. The project will graduate from alpha when the safety gate is fully verified for all mutation types and the system can demonstrate long-term coherence in planning and task execution without human intervention for trivial steps.

Establishing Nexus as a research platform

Nexus has evolved from an experimental coding assistant into a broader investigation of persistent AI systems. We are moving away from session-oriented interaction models toward a knowledge base built from verifiable evidence. Our research focuses on whether an AI can maintain a durable, auditable, and safely governed understanding of software projects and personal context over long durations.

Architectural design and methodology

The system is a Python 3.13 monorepo using FastAPI as the composition root. We enforce strict separation between reasoning and execution: models propose actions, while deterministic runtime systems validate schemas, capabilities, and policies. Repository mutations are protected by path jailing and shadow-git checkpoints, ensuring every effect can be rolled back if necessary.

CLI / REST request -> FastAPI root -> ContextAssembler -> ModelRouter -> Planner / ToolLoop -> Policy / Confirmation / Checkpoint -> Observation Ledger

We treat state machines and structural protocols as primary seams. This allows individual components—such as memory retrievers, storage providers, and model routers—to evolve independently without requiring monolithic changes.

Engineering challenges and observations

• Memory provenance: Storing information is trivial; maintaining a truthful, rollback-aware memory that identifies its source and verification state is complex.
• Autonomy vs. safety: Meaningful automation relies on deterministic infrastructure that validates effects, not just sophisticated language models.
• Performance: Scalable context assembly and concurrent tool execution remain primary bottlenecks in the current alpha implementation.

Current limitations

Nexus remains an alpha research project. Significant work is still required to stabilize the Sprint 15 implementation, including generalized repository mutation, bounded parallel tool execution, and the transition from process-local caching to distributed backends like Redis. We currently prioritize correctness and safety guarantees over feature breadth.

Next steps

Development is currently focused on Sprint 15: Personal Intelligence. Our objective is to unify software project knowledge with personal information models—reminders, goals, and routines—using the existing safety and provenance framework. This will provide the foundation for future proactive assistance while maintaining strict human oversight.

Project Nexus: Research Findings

Nexus is an active research program investigating whether an AI engineering assistant can maintain a durable, trustworthy model of a software project across sessions. The core hypothesis is that long-term utility requires persistent memory, grounded context assembly, provider-neutral architecture, and a universal safety boundary for all autonomous actions.

Confirmed Findings

Protocol-first modularity enables provider-neutral systems. By using structural protocols to define boundaries between leaf services and the FastAPI composition root, we successfully interchanged Anthropic, Ollama, and null providers without modifying core business logic.

A universal capability gate is the most effective path toward safe autonomy. Rather than granting models broad execution surfaces, we established a lifecycle requiring registry resolution, schema validation, policy checks, and human confirmation before mutation. This fail-closed architecture proved essential for isolating risky operations.

Assumptions That Changed

Initially, we believed a tamper-evident ledger was sufficient to guarantee the integrity of agent actions. We discovered that hash-chaining is meaningless without canonical data models and durable, checkpoint-aware rollback semantics. If a mutation is rolled back but the ledger records it as successful, the system creates a durable false belief.

We also assumed that human confirmation was a sufficient safety check. We found that approval is only meaningful when bound to a concrete, executor-computed effect preview. If the preview drifts from the final execution, the confirmation is effectively decoupled from the outcome.

Unexpected Discoveries

Denied actions are frequently more valuable for memory distillation than successful reads. They provide explicit signals regarding safety boundaries, sensitive paths, and user preferences that rarely appear in routine operational data.

The project revealed that rollback is an epistemic concern as much as a filesystem concern. An assistant must not remember effects that have been reverted; memory formation must respect the state of the repository at the end of an episode, not just the intent of the model.

Remaining Research Questions

• How to prune retention for the growing observation ledger without losing critical provenance.
• How to implement bounded parallel read execution while maintaining call-index order consistency.
• How to resolve cross-project memory sharing while respecting project-specific safety policies.
• Whether the proposed Conscience Engine and value hierarchy can provide explainable reasoning without introducing significant latency.

Implications for Future Development

Future work will prioritize Sprint 15 personal intelligence features while hardening the mutation pipeline. The distinction between 'inline' (cheap, irreversible facts) and 'deferred' (mutation-dependent) work will remain the primary boundary for correctness in all agent-memory interactions.

Research Context

Nexus is an active alpha experiment investigating the viability of a persistent, grounded AI agent for software engineering. Current session-scoped assistants suffer from memory loss, failing to retain the rationale behind architectural constraints or prior task states. Our goal is to move from temporary prompt-response cycles to a durable, provenance-aware operational model.

Current Hypotheses

• Persistent, provenance-aware memory is required for long-lived assistant utility.
• Context assembly must be grounded in current repository state and history, not just model training data.
• Autonomy should be restricted by an auditable, fail-closed capability gate rather than unrestricted tool access.
• Human approval must be bound to a recomputed effect preview, not an abstract natural-language description.

Architectural Explorations

The system architecture uses a protocol-first monorepo pattern. Leaf services expose business logic through structural protocols, with implementations injected via a FastAPI composition root. This approach allows components—such as model providers, memory retrievers, and tool adapters—to be swapped or mocked for testing without modifying core logic.

CLI / REST request -> FastAPI composition root -> ContextAssembler -> ModelRouter -> ToolLoop/Planner -> Policy/Checkpoint -> Observation Ledger

Open Technical Questions

• How do we handle memory decay for operational facts that become stale as the repository evolves?
• Can we reconcile the performance requirements of blocking subprocess calls (git/ripgrep) within an async event loop?
• What is the optimal threshold for promoting observed events into long-term distilled memory versus inline logs?
• How can we extend the universal capability gate to non-filesystem resources like external APIs or personal data without introducing new security vectors?

Alternative Designs Considered

We evaluated using a standard headless CMS for project state but rejected it to prioritize local-first persistence. We also considered direct model-authored state updates for personal intelligence, but the risk of 'approve A, execute B' vulnerabilities forced a shift to an inert proposal-and-commit model.

Risks and Unknowns

The observation ledger currently relies on application-level enforcement for append-only integrity, rather than database-level triggers. We have identified a significant risk where mismatched serialization on read/write can invalidate hash-chained provenance. Furthermore, full-suite verification is currently hampered by long execution times, making CI stabilization a primary blocker.

Future Experiments

• Complete Sprint 15 implementation for personal intelligence (reminders, routines, and profile).
• Transition from process-local caching to Redis to support multi-worker consistency.
• Implement the 'Conscience Engine' for reasoned policy evaluation and value-aligned autonomous behavior.
• Enable bounded parallel read execution while maintaining strict quiescence for mutation operations.