# avenoxai/avenoxbeyin architecture

> Architecture diagram of the GitHub repository avenoxai/avenoxbeyin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avenoxai/avenoxbeyin
- Repository: https://github.com/avenoxai/avenoxbeyin

## Overview

Avenoxbeyin V3 is a local-first second brain for AI coding assistants: agents save and retrieve source-linked knowledge in an editable Markdown vault, with shared state across clients. The main workflow runs on client lifecycle events: the installed adapters invoke the local runtime, which refreshes vault indexing and supplies bounded context; agents can also record outcomes and tasks for later retrieval or recap. The README documents companion continuity, preferences, diagnostics, updates, and optional Jev/Laya advice. Several runtime links are based on documented behavior and module names; source excerpts are partial.

Main entry points: [`scripts/beyin_v3.py`](https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_v3.py) (Runtime CLI), [`scripts/beyin_entry.py`](https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_entry.py) (Vault entry), [`template/.claude/scripts/beyin_v3.py`](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3.py) (Memory store), [`template/.claude/scripts/beyin_v3_sync.py`](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_sync.py) (Vault sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client integration"]
  node_adapters["Client adapters<br/>[beyin_v3_hook.py]"]
  node_skills["Agent skills<br/>[SKILL.md]"]
end

subgraph group_memory["Memory workflow"]
  node_entry["Vault entry<br/>[beyin_entry.py]"]
  node_cli["Runtime CLI<br/>[beyin_v3.py]"]
  node_sync["Vault sync<br/>[beyin_v3_sync.py]"]
  node_store["Memory store<br/>[beyin_v3.py]"]
  node_passages["Passage retrieval"]
  node_receipts["Work receipts"]
  node_companion["Companion continuity"]
end

subgraph group_state["State and controls"]
  node_database[("Local runtime state")]
  node_preferences["Vault preferences"]
  node_doctor["Health checks<br/>[beyin_v3.py]"]
  node_updater["Install and update<br/>[beyin_v3_update.py]"]
end

subgraph group_extensions["Extensions"]
  node_jev["Jev advisor<br/>[beyin_v3_jev.py]"]
  node_jevclient["Jev provider client"]
end

node_user(("User"))
node_agent(("AI agent"))
node_vault["Markdown vault"]
node_clients["AI clients"]
node_typesafe["TypeSafe API"]
node_laya["Local Laya server"]

node_user -->|"asks or instructs"| node_agent
node_agent -->|"uses guidance"| node_skills
node_clients -->|"dispatches events"| node_adapters
node_adapters -->|"invokes"| node_entry
node_agent -->|"runs commands"| node_entry
node_entry -->|"dispatches"| node_cli
node_cli -->|"refreshes index"| node_sync
node_sync -->|"reads and syncs"| node_vault
node_sync -->|"indexes records"| node_store
node_store -->|"reads and writes"| node_database
node_store -->|"retrieves passages"| node_passages
node_cli -->|"requests context"| node_store
node_entry -->|"returns context"| node_agent
node_agent -->|"edits notes"| node_vault
node_agent -->|"updates continuity"| node_companion
node_companion -->|"reads and writes"| node_vault
node_cli -->|"lists receipts"| node_receipts
node_receipts -->|"reads receipts"| node_database
node_cli -->|"manages settings"| node_preferences
node_preferences -->|"stores preferences"| node_database
node_cli -->|"runs diagnostics"| node_doctor
node_cli -->|"runs update"| node_updater
node_cli -.->|"requests advice"| node_jev
node_jev -.->|"evaluates with"| node_jevclient
node_jevclient -.->|"sends advice request"| node_typesafe
node_jevclient -.->|"sends shadow request"| node_laya

click node_adapters "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_hook.py"
click node_skills "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.agents/skills/beyin/SKILL.md"
click node_entry "https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_entry.py"
click node_cli "https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_v3.py"
click node_sync "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_sync.py"
click node_store "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3.py"
click node_passages "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_passage.py"
click node_receipts "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_projections.py"
click node_companion "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_companion.py"
click node_preferences "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_preferences.py"
click node_doctor "https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_v3.py"
click node_updater "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_update.py"
click node_jev "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_jev.py"
click node_jevclient "https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_jev_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_adapters,node_skills,node_user,node_clients toneBlue
class node_entry,node_cli,node_sync,node_store,node_passages,node_receipts,node_companion toneAmber
class node_database,node_preferences,node_doctor,node_updater,node_typesafe,node_laya toneMint
class node_jev,node_jevclient toneRose
class node_agent,node_vault toneIndigo
```

## Components

### Client integration

- [Client adapters](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_hook.py): `template/.claude/scripts/beyin_v3_hook.py`
- [Agent skills](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.agents/skills/beyin/SKILL.md): `template/.agents/skills/beyin/SKILL.md`

### Memory workflow

- [Vault entry](https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_entry.py): `scripts/beyin_entry.py`
- [Runtime CLI](https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_v3.py): `scripts/beyin_v3.py`
- [Vault sync](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_sync.py): `template/.claude/scripts/beyin_v3_sync.py`
- [Memory store](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3.py): `template/.claude/scripts/beyin_v3.py`
- [Passage retrieval](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_passage.py): `template/.claude/scripts/beyin_v3_passage.py`
- [Work receipts](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_projections.py): `template/.claude/scripts/beyin_v3_projections.py`
- [Companion continuity](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_companion.py): `template/.claude/scripts/beyin_v3_companion.py`

### State and controls

- **Local runtime state**
- [Vault preferences](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_preferences.py): `template/.claude/scripts/beyin_v3_preferences.py`
- [Health checks](https://github.com/avenoxai/avenoxbeyin/blob/main/scripts/beyin_v3.py): `scripts/beyin_v3.py`
- [Install and update](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_update.py): `template/.claude/scripts/beyin_v3_update.py`

### Extensions

- [Jev advisor](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_jev.py): `template/.claude/scripts/beyin_v3_jev.py`
- [Jev provider client](https://github.com/avenoxai/avenoxbeyin/blob/main/template/.claude/scripts/beyin_v3_jev_client.py): `template/.claude/scripts/beyin_v3_jev_client.py`

### Other components

- **User**
- **AI agent**
- **Markdown vault**
- **AI clients**
- **TypeSafe API**
- **Local Laya server**

## Connections

- User → AI agent: asks or instructs
- AI agent → Agent skills: uses guidance
- AI clients → Client adapters: dispatches events
- Client adapters → Vault entry: invokes
- AI agent → Vault entry: runs commands
- Vault entry → Runtime CLI: dispatches
- Runtime CLI → Vault sync: refreshes index
- Vault sync → Markdown vault: reads and syncs
- Vault sync → Memory store: indexes records
- Memory store → Local runtime state: reads and writes
- Memory store → Passage retrieval: retrieves passages
- Runtime CLI → Memory store: requests context
- Vault entry → AI agent: returns context
- AI agent → Markdown vault: edits notes
- AI agent → Companion continuity: updates continuity
- Companion continuity → Markdown vault: reads and writes
- Runtime CLI → Work receipts: lists receipts
- Work receipts → Local runtime state: reads receipts
- Runtime CLI → Vault preferences: manages settings
- Vault preferences → Local runtime state: stores preferences
- Runtime CLI → Health checks: runs diagnostics
- Runtime CLI → Install and update: runs update
- Runtime CLI → Jev advisor: requests advice
- Jev advisor → Jev provider client: evaluates with
- Jev provider client → TypeSafe API: sends advice request
- Jev provider client → Local Laya server: sends shadow request