Marvis architecture: a 16-edge cross-project knowledge graph with audit-grade memory and Brain-style reflection

Abstract

Marvis is an open-source Company Brain designed to serve as a shared substrate for human developers and AI agents working on the same codebase across multiple projects. The system addresses three operational queries underserved by existing platforms: cross-project impact analysis, immutable decision audit, and agent-native knowledge sharing without re-onboarding cost.

The architecture spans eight functional domains (capture, store, retrieve, reflect, execute, agent-native, trust, productization). The core is a knowledge graph with sixteen deterministic edge types, combined with an append-only foreign-key-linked audit log and a five-layer cognitive reflection loop. We release the architecture for defensive-publication purposes under CC-BY 4.0.

Introduction

AI agents lose context across sessions, human developers lose context across projects, and organisations cannot answer simple audit questions ("who approved this change on date X?") without manual archaeology through chat threads and wiki pages.

Across a survey of adjacent platforms (agent-memory, enterprise search, data-catalog, PM incumbents), two queries have no first-class primitive: cross-project deterministic impact analysis, and immutable decision audit. Marvis is positioned to answer both natively.

The 16-edge knowledge graph

The Marvis knowledge graph defines 16 deterministic edge types over a typed node space. Nodes carry the identifier format {prefix}:{kind}:{slug}, where prefix denotes the source domain (py, ts, task, pr, commit, handoff, learning, audit, and more) and kind denotes the role (function, file, module, artifact, sheet).

The edges fall into five categories:

• Code edges — calls, imports, defines, extracted from an AST parse, enable deterministic impact traversal.
• Work chain — produces, contains, link commits, PRs, tasks, and artefacts.
• Knowledge chain — describes, documents, cites, applies_to, link prose artefacts (handoffs, learnings, plans) to code or other artefacts.
• Cross-project — depends_on, mentions, refers_to, shares_tag, similar_to, link artefacts across project boundaries.
• Bridge — resolves_to, maps module stubs to canonical files (invariant: stub to canonical, never the reverse).

A watcher daemon listens to filesystem events and replays tree-sitter parsers over modified files. Each edge insert is idempotent (UPSERT on the source, destination, and edge type) and time-stamped, enabling time-travel as_of queries.

The five knowledge forms

Organisational memory is heterogeneous, and a single "document" abstraction obscures critical lifecycle differences. Marvis defines five typed forms:

• ADR — architecture decisions, frozen at write time, immutable, FK-linked to author, date, and context.
• Spec — formal requirements, versioned and machine-readable, with a draft to ratified to superseded lifecycle.
• Playbook — procedural runbooks (incident response, deploy, onboarding), mutable with tracked revisions.
• Tribal — institutional context not yet codified, mutable and salience-scored.
• External — third-party reference material, a read-only mirror that is citation-tracked.

Brain reflection: a five-layer loop

The Brain layer is a periodic cognitive cycle over the substrate:

• L1 Substrate — raw events (commits, task transitions, ingest insertions, agent tool calls) in an append-only stream.
• L2 Journal — narrative aggregation per scope, with what_changed, decisions_observed, open_loops, and tomorrow_watch.
• L3 Drift — observed-versus-expected gaps, severity-scored and axis-tagged.
• L4 Memory operations — proposed writes (reinforce, consolidate, supersede candidate, provenance hardening), all approval-gated.
• L5 Findings — conclusions ratifiable into the substrate as ADRs, learnings, or guides, confidence-tiered and approval-gated.

Audit-grade memory

Every state-changing tool call writes to audit_log with foreign-key links to the task, PR, actor, and project that originated the call. The table is append-only at the database level: the runtime user has no UPDATE or DELETE grants. Timestamps use the database transaction clock to prevent agent-side time skew.

This pattern aligns with EU AI Act Art. 12 (record-keeping) and DORA operational-resilience requirements, and it passes Series-B due-diligence audit asks in seconds.

Constitution hooks

Five immutable rules are enforced at the filesystem level via git hooks and pre-tool wrappers:

• Task First — every code change requires a tracked task.
• No Hotfix Prod — no direct writes to the deployed runtime.
• No Merge on Main — merges only after Triage approval.
• Worktree for Code — code edits only in isolated worktrees.
• No Bypass Orchestrator — no subtree push or direct deploy.

Hooks are deterministic, fail-closed, and apply identically to human and agent actors.

EU AI Act alignment

The architecture aligns with three Article 12 requirements out of the box: automatic logging of system events, FK-linked record provenance, and time-stamped retention with privacy controls. Self-host deployment satisfies the obligation that records stay under the operator's direct control, a pattern multi-tenant managed SaaS cannot trivially satisfy without per-tenant log isolation.

Frequently asked questions

What makes the Marvis knowledge graph different from a code graph?

A code graph captures calls, imports, and defines. Marvis adds thirteen more deterministic edges across the work chain, the knowledge chain, and cross-project links, plus a resolves_to bridge. That is what lets a chat thread, a PR, a learning note, and a function be queried together across project boundaries.

How does the audit log satisfy EU AI Act Article 12?

Every state-changing call writes to an append-only audit_log with foreign keys to the task, PR, actor, and project. The runtime role has no UPDATE or DELETE grants, and timestamps use the database transaction clock. That provides automatic logging, FK-linked provenance, and time-stamped retention under the operator's direct control.

Does the Brain reflection loop write to memory automatically?

No. The loop observes, journals, detects drift, proposes operations, and surfaces findings, but every promotion to a durable artefact is approval-gated. Findings carry a confidence tier and a severity tier and are never auto-applied.