A
Constellation architectureDocumentation

Arcturion Architecture

Arcturion architecture โ€” folders people can read, context agents can follow

A file-first design for AI agents. People can walk through it, and agents can boot from it.

This architecture gives working state a home in named files and folders. A person can open a folder and see what an agent is responsible for, what it is working on and what it has prepared for review. An agent starts from an explicit boot order and knows which floor it owns. It follows links instead of guessing, and it recalls past context by asking a question instead of reading everything.

This repository is a public tour of a private working system. It also includes a small synthetic template that you can inspect, check and adapt.

๐Ÿ”ญ Two readers, one structure

Reader What the structure gives them
๐Ÿ‘ค People Numbered floors with plain names, an overview page at the front, a back office, a deliverables shelf and an archive. Working state is meant to live in files, not only inside a model's context.
๐Ÿค– Agents A boot manifest that lists what to load and in what order, clear ownership of each floor, relative links between sources, and recall through a query that returns pointers back to each source.

The same folders serve both readers, and the rest of the design follows from that choice.

๐Ÿ—บ The system at a glance

Scroll diagram to explore.

work for review

Person: direction and review

Shared HQ
governance ยท skills ยท projects

Agent workspaces
boot ยท domain work ยท deliverables

ATLAS
documents by subject

Runtime
installed tools and services

Brain
index ยท retrieval ยท source pointers

There are four working areas, and each has one job:

  • Agent workspaces hold each specialist's identity, domain work and deliverables.
  • The shared HQ holds the governance, skills and project coordination that all agents use.
  • ATLAS is the document workspace, organized by subject.
  • The runtime holds installed tools, services and dependencies.

The Brain is not a fifth area. It connects the other four: it indexes selected sources and returns a limited amount of context, with a pointer back to each source. Dashed lines show indexing relationships. They do not mean files sync automatically. The system map follows one piece of work through every area.

๐Ÿ  One agent's workspace

The sample agent is a fictional adaptation of the inspected ARCTURUS orchestration workspace, combining shared core shelves with role-specific floors and extensions:

sample-agent/
โ”œโ”€โ”€ 00 ๐Ÿ›ก Governance/              local rules and example shared references
โ”œโ”€โ”€ 000 ๐Ÿค– Aster/                  the agent's core
โ”‚   โ”œโ”€โ”€ Boot/                      manifest, identity, voice, context
โ”‚   โ”œโ”€โ”€ Knowledge/                 Foundations ยท Founder ยท Lessons ยท Methods
โ”‚   โ”‚                              Patterns ยท Sources ยท Standards
โ”‚   โ”œโ”€โ”€ Memory/                    Decisions ยท People ยท Pointers
โ”‚   โ”‚                              Preferences ยท Sessions
โ”‚   โ”œโ”€โ”€ Identity/ ยท dashboard/     role-specific structural shelves
โ”‚   โ”œโ”€โ”€ Skills/ ยท Tools/           what it can do, and with what
โ”‚   โ”œโ”€โ”€ Inbox/                     incoming work and intel
โ”‚   โ”œโ”€โ”€ Heartbeats & Automations/  scheduled routines
โ”‚   โ””โ”€โ”€ Photo/
โ”œโ”€โ”€ 01 ๐Ÿ–ฅ๏ธ Jurisdiction Overview/   the front door to its domain
โ”œโ”€โ”€ 02โ€“07                         strategy, orchestration, health, brand,
โ”‚                              coherence and growth floors
โ”œโ”€โ”€ 09_Linked_Surfaces/            links to shared surfaces (empty here)
โ”œโ”€โ”€ 77 ๐Ÿ›  Back Office/             internal operations
โ”œโ”€โ”€ 88 ๐Ÿ“ฆ Deliverables/            work prepared for human review
โ”œโ”€โ”€ 99 ๐Ÿ—„๏ธ Archive/                 retired material, out of the way
โ””โ”€โ”€ AGENTS.md, CLAUDE.md, โ€ฆ        five generated entry pointers

The common floors. 00 holds the agent's local governance. 000 is the core, with these parts:

  • The boot manifest and identity files.
  • Two separate shelves: Knowledge for how to do the work, and Memory for what happened.
  • Skills, tools, an inbox and scheduled routines.

01 is the front door. Across the inspected workspaces, floors 77, 88 and 99 keep the same roles: internal operations, deliverables and retired material.

What changes per specialist. Domain floors 02โ€“07 are renamed to match each agent's responsibilities, and some specialists add more floors. Extra inner folders such as Identity, Crew, dashboard, domains or logs appear only where a role needs them. These are optional extensions, not requirements. Aster includes Identity and dashboard as role-specific examples.

๐Ÿ“š ATLAS: a place for the work

ATLAS is the document workspace. It uses numbered subject areas, ordinary folders and readable documents, with links and indexes for moving between them. A document belongs where people can find it and keep it up to date. The public tour maps its numbered areas with privacy-generalized labels and shows selected shared-system subtrees without private contents. โ†’ docs/atlas.md

๐Ÿง  The Brain: anatomy and physiology

Anatomy (how it is built). Extractors read approved sources and record each one's title, path, summary, timestamps, content hash and links. A graph builder turns these records into nodes connected by typed relationships, stored in SQLite. The same database holds aliases, a full-text index and space for embeddings.

Physiology (how it works).

  1. A question arrives with a scope.
  2. Retrieval looks for matches by exact ID, alias, title and full-text search, plus a vector search where one is available.
  3. It follows selected relationships to related records.
  4. It returns a context pack that fits a token budget, with a pointer to each source.

Reading and proposed changes follow separate paths. The inspected MCP proposal interface validates fields, scans relevant text for secret patterns and stages proposals for review. That describes the proposal path; it does not certify every ingestion or administrative write.

A pointer tells you where to look next. It is not proof. โ†’ docs/brain.md

๐Ÿš€ Boot: a small fixed kernel, then only what the task needs

The adaptive design starts an agent from a protected kernel: its exact identity and voice files, a shared operating card and a small routing block. These are loaded word for word and never summarized to fit. The private adaptive controller blocks activation if that kernel exceeds its ceiling. The source configuration caps the kernel at 14,000 estimated tokens, which is within a 15k design target for the agent boot. That is a limit set in source code, not a measured live footprint.

Everything else loads only when the task calls for it, and past context comes through the Brain. In this design, "identity" means a written role, voice, ownership and authority that a person with workspace access can inspect. โ†’ docs/boot.md

๐Ÿ“ฆ What is in this repository

Included and runnable

  • sample-agent/: a fictional orchestration workspace adapted from an inspected modern layout, with a synthetic boot manifest and example identity files.
  • sample-agent/tools/render_entrypoints.py: a generator, limited to the sample, that writes the five harness entry pointers from one shared manifest. It comes with regression tests.
  • scripts/check_architecture.py: a read-only checker for folders, local links, symlinks and generated pointers.

Documented but not included

  • The private Brain service, the context controller, and the controllers, hooks and governance enforcement that run the private system. The pages here describe them from their source code. They are not a release of that code.

โ–ถ๏ธ Check it yourself

You need Python 3.11 or newer. Run these from the repository root:

python3 scripts/check_architecture.py
python3 -m unittest discover -s sample-agent/tools -p 'test_*.py'
python3 -m unittest discover -s scripts -p 'test_*.py'

Nothing here installs an agent, starts a service or touches an account.

  • Arcturion Memory: audit, index, deduplicate and recall document-based agent memory.
  • Arcturion Evals: synthetic tasks for studying agent behavior over time.

Both are separate projects. Neither is the private Brain or vault.

๐Ÿค Follow and contribute

  • โญ Follow Arcturion Technologies for the public work. Star or watch this repository to follow changes.
  • ๐Ÿงฉ Open an issue with a specific architecture question, a broken link, or a folder or boot convention you would change. Include a small fictional example and the tradeoff.
  • ๐Ÿ›  Contribute improvements to the docs, the template, the pointer generator or the checker, with steps others can reproduce. See CONTRIBUTING.md.

Use invented data only. Never attach a real memory archive, a production graph or credentials.

License

MIT, covering the original content of this repository. Linked projects and third-party material keep their own terms.