Arcturion Architecture
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.
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).
- A question arrives with a scope.
- Retrieval looks for matches by exact ID, alias, title and full-text search, plus a vector search where one is available.
- It follows selected relationships to related records.
- 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.
๐ฐ Related public tools
- 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.