# muxuejc/norma architecture

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

- Interactive diagram: https://gitdiagram.com/muxuejc/norma
- Repository: https://github.com/muxuejc/norma

## Overview

Norma is a Go agent-harness SDK. A host supplies a prompt and provider, then drives a stateful Session that streams model output, dispatches permitted tools, and returns results. The graph also preserves the documented context management, integrations, and agent extensions, plus the substantial NOA context subsystem present in the source tree. Edges reflect README statements or shown/indexed references; unsampled implementations are represented without guessed call paths.

Main entry points: [`agentcore/agentcore.go`](https://github.com/muxuejc/norma/blob/main/agentcore/agentcore.go) (Session API), [`harness/query.go`](https://github.com/muxuejc/norma/blob/main/harness/query.go) (Streaming Loop), [`noaadapter/session.go`](https://github.com/muxuejc/norma/blob/main/noaadapter/session.go) (NOA Session), [`tool/registry.go`](https://github.com/muxuejc/norma/blob/main/tool/registry.go) (Tool Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent Runtime"]
  node_session["Session API<br/>[agentcore.go]"]
  node_loop["Streaming Loop<br/>[query.go]"]
  node_provider["Provider Adapters<br/>[anthropic.go]"]
  node_events["Stream Events<br/>[event.go]"]
end

subgraph group_safety_tools["Safety and Tools"]
  node_permissions["Permission Policy<br/>[permission.go]"]
  node_tool_registry["Tool Registry<br/>[registry.go]"]
  node_core_tools["Core Tools<br/>[files.go]"]
  node_web_search["Web Search<br/>[websearch.go]"]
  node_background_tasks["Background Tasks<br/>[task.go]"]
end

subgraph group_context["Context and Persistence"]
  node_compaction["Context Compaction<br/>[compaction.go]"]
  node_summarizer["Summarizer<br/>[summarizer.go]"]
  node_transcript[("Transcript Store<br/>[transcript.go]")]
end

subgraph group_extensions["Agent Extensions"]
  node_hooks["Lifecycle Hooks<br/>[hook.go]"]
  node_subagents["Subagents<br/>[subagent.go]"]
  node_coordinator["Coordinator<br/>[coordinator.go]"]
  node_mcp["MCP Integration<br/>[mcp.go]"]
  node_plan["Plan Mode<br/>[plan.go]"]
  node_memory[("Long-Term Memory<br/>[memory.go]")]
  node_skills["Skill System<br/>[skill.go]"]
end

subgraph group_noa["NOA Context"]
  node_noa_session["NOA Session<br/>[session.go]"]
  node_noa_projection["History Projection<br/>[project.go]"]
  node_noa_state[("NOA State Store<br/>[state_store.go]")]
  node_noa_engine["NOA Compression<br/>[compress.go]"]
end

node_host(("SDK Host"))
node_model(("LLM Service"))

node_host -->|"configures and prompts"| node_session
node_session -->|"runs query"| node_loop
node_loop -->|"streams completion"| node_provider
node_provider -->|"sends requests"| node_model
node_loop -->|"emits events"| node_events
node_loop -->|"evaluates calls"| node_permissions
node_loop -->|"dispatches tools"| node_tool_registry
node_tool_registry -.->|"registers tools"| node_core_tools
node_tool_registry -.->|"registers optionally"| node_web_search
node_session -->|"manages context"| node_compaction
node_compaction -->|"summarizes history"| node_summarizer
node_loop -->|"records messages"| node_transcript
node_session -.->|"configures callbacks"| node_hooks
node_session -.->|"exposes delegation"| node_subagents
node_coordinator -->|"runs workers"| node_subagents
node_session -.->|"adds MCP tools"| node_mcp
node_session -.->|"enables plan mode"| node_plan
node_session -.->|"adds memory tools"| node_memory
node_session -->|"adds skill tool"| node_skills
node_session -.->|"manages task tools"| node_background_tasks
node_noa_session -.->|"projects history"| node_noa_projection
node_noa_session -.->|"loads and stores state"| node_noa_state
node_noa_session -.->|"applies compression"| node_noa_engine
node_noa_projection -->|"uses NOA model"| node_noa_engine

click node_session "https://github.com/muxuejc/norma/blob/main/agentcore/agentcore.go"
click node_loop "https://github.com/muxuejc/norma/blob/main/harness/query.go"
click node_provider "https://github.com/muxuejc/norma/blob/main/llm/anthropic.go"
click node_events "https://github.com/muxuejc/norma/blob/main/harness/event.go"
click node_permissions "https://github.com/muxuejc/norma/blob/main/permission/permission.go"
click node_tool_registry "https://github.com/muxuejc/norma/blob/main/tool/registry.go"
click node_core_tools "https://github.com/muxuejc/norma/blob/main/tool/files.go"
click node_web_search "https://github.com/muxuejc/norma/blob/main/tool/websearch.go"
click node_compaction "https://github.com/muxuejc/norma/blob/main/compaction/compaction.go"
click node_summarizer "https://github.com/muxuejc/norma/blob/main/compaction/summarizer.go"
click node_transcript "https://github.com/muxuejc/norma/blob/main/transcript/transcript.go"
click node_hooks "https://github.com/muxuejc/norma/blob/main/hook/hook.go"
click node_subagents "https://github.com/muxuejc/norma/blob/main/subagent/subagent.go"
click node_coordinator "https://github.com/muxuejc/norma/blob/main/coordinator/coordinator.go"
click node_mcp "https://github.com/muxuejc/norma/blob/main/mcp/mcp.go"
click node_plan "https://github.com/muxuejc/norma/blob/main/plan/plan.go"
click node_memory "https://github.com/muxuejc/norma/blob/main/memory/memory.go"
click node_skills "https://github.com/muxuejc/norma/blob/main/skill/skill.go"
click node_background_tasks "https://github.com/muxuejc/norma/blob/main/tool/task.go"
click node_noa_session "https://github.com/muxuejc/norma/blob/main/noaadapter/session.go"
click node_noa_projection "https://github.com/muxuejc/norma/blob/main/noaadapter/project.go"
click node_noa_state "https://github.com/muxuejc/norma/blob/main/noaadapter/state_store.go"
click node_noa_engine "https://github.com/muxuejc/norma/blob/main/noa/compress.go"

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_session,node_loop,node_provider,node_events toneBlue
class node_permissions,node_tool_registry,node_core_tools,node_web_search,node_background_tasks toneAmber
class node_compaction,node_summarizer,node_transcript toneMint
class node_hooks,node_subagents,node_coordinator,node_mcp,node_plan,node_memory,node_skills toneRose
class node_noa_session,node_noa_projection,node_noa_state,node_noa_engine,node_host,node_model toneIndigo
```

## Components

### Agent Runtime

- [Session API](https://github.com/muxuejc/norma/blob/main/agentcore/agentcore.go): `agentcore/agentcore.go`
- [Streaming Loop](https://github.com/muxuejc/norma/blob/main/harness/query.go): `harness/query.go`
- [Provider Adapters](https://github.com/muxuejc/norma/blob/main/llm/anthropic.go): `llm/anthropic.go`
- [Stream Events](https://github.com/muxuejc/norma/blob/main/harness/event.go): `harness/event.go`

### Safety and Tools

- [Permission Policy](https://github.com/muxuejc/norma/blob/main/permission/permission.go): `permission/permission.go`
- [Tool Registry](https://github.com/muxuejc/norma/blob/main/tool/registry.go): `tool/registry.go`
- [Core Tools](https://github.com/muxuejc/norma/blob/main/tool/files.go): `tool/files.go`
- [Web Search](https://github.com/muxuejc/norma/blob/main/tool/websearch.go): `tool/websearch.go`
- [Background Tasks](https://github.com/muxuejc/norma/blob/main/tool/task.go): `tool/task.go`

### Context and Persistence

- [Context Compaction](https://github.com/muxuejc/norma/blob/main/compaction/compaction.go): `compaction/compaction.go`
- [Summarizer](https://github.com/muxuejc/norma/blob/main/compaction/summarizer.go): `compaction/summarizer.go`
- [Transcript Store](https://github.com/muxuejc/norma/blob/main/transcript/transcript.go): `transcript/transcript.go`

### Agent Extensions

- [Lifecycle Hooks](https://github.com/muxuejc/norma/blob/main/hook/hook.go): `hook/hook.go`
- [Subagents](https://github.com/muxuejc/norma/blob/main/subagent/subagent.go): `subagent/subagent.go`
- [Coordinator](https://github.com/muxuejc/norma/blob/main/coordinator/coordinator.go): `coordinator/coordinator.go`
- [MCP Integration](https://github.com/muxuejc/norma/blob/main/mcp/mcp.go): `mcp/mcp.go`
- [Plan Mode](https://github.com/muxuejc/norma/blob/main/plan/plan.go): `plan/plan.go`
- [Long-Term Memory](https://github.com/muxuejc/norma/blob/main/memory/memory.go): `memory/memory.go`
- [Skill System](https://github.com/muxuejc/norma/blob/main/skill/skill.go): `skill/skill.go`

### NOA Context

- [NOA Session](https://github.com/muxuejc/norma/blob/main/noaadapter/session.go): `noaadapter/session.go`
- [History Projection](https://github.com/muxuejc/norma/blob/main/noaadapter/project.go): `noaadapter/project.go`
- [NOA State Store](https://github.com/muxuejc/norma/blob/main/noaadapter/state_store.go): `noaadapter/state_store.go`
- [NOA Compression](https://github.com/muxuejc/norma/blob/main/noa/compress.go): `noa/compress.go`

### Other components

- **SDK Host**
- **LLM Service**

## Connections

- SDK Host → Session API: configures and prompts
- Session API → Streaming Loop: runs query (evidence: `agentcore/agentcore.go`)
- Streaming Loop → Provider Adapters: streams completion
- Provider Adapters → LLM Service: sends requests
- Streaming Loop → Stream Events: emits events
- Streaming Loop → Permission Policy: evaluates calls
- Streaming Loop → Tool Registry: dispatches tools
- Tool Registry → Core Tools: registers tools
- Tool Registry → Web Search: registers optionally
- Session API → Context Compaction: manages context (evidence: `agentcore/agentcore.go`)
- Context Compaction → Summarizer: summarizes history (evidence: `compaction/compaction.go`)
- Streaming Loop → Transcript Store: records messages (evidence: `harness/query.go`)
- Session API → Lifecycle Hooks: configures callbacks
- Session API → Subagents: exposes delegation
- Coordinator → Subagents: runs workers (evidence: `coordinator/coordinator.go`)
- Session API → MCP Integration: adds MCP tools
- Session API → Plan Mode: enables plan mode
- Session API → Long-Term Memory: adds memory tools
- Session API → Skill System: adds skill tool (evidence: `agentcore/agentcore.go`)
- Session API → Background Tasks: manages task tools
- NOA Session → History Projection: projects history
- NOA Session → NOA State Store: loads and stores state
- NOA Session → NOA Compression: applies compression
- History Projection → NOA Compression: uses NOA model (evidence: `noaadapter/project.go`)
