# gregmos/memoforge architecture

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

- Interactive diagram: https://gitdiagram.com/gregmos/memoforge
- Repository: https://github.com/gregmos/memoforge

## Overview

Memoforge is a legal-research workflow that turns a question into an audited, cited memorandum, primarily through the Claude/Cowork model’s `next → act → report` protocol and the Python `mf` CLI. The README documents intake, routed research, source freezing, drafting, review, revision and export, plus multilingual output, decision briefs and dependency fallbacks. The graph preserves those capabilities; some subsystem links use README-level evidence because their source was not sampled.

Main entry points: [`scripts/memoforge/machine.py`](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/machine.py) (Workflow machine), [`scripts/memoforge/cli.py`](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/cli.py) (mf CLI), [`scripts/memoforge/docx/renderer.py`](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/docx/renderer.py) (DOCX renderer), [`scripts/memoforge/sources.py`](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/sources.py) (Source registry and freeze)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_machine["Workflow machine<br/>[machine.py]"]
  node_intake["Intake and gates<br/>[gates.py]"]
  node_routing["Jurisdiction routing<br/>[routing.py]"]
  node_research["Legal research<br/>[analyze.py]"]
  node_draft["Memo drafting<br/>[draft.py]"]
end

subgraph group_evidence["Evidence and quality"]
  node_sources["Source registry and freeze<br/>[sources.py]"]
  node_quotes["Quote verification<br/>[quotes.py]"]
  node_citations["Citation provenance<br/>[citations.py]"]
  node_lint["Draft lint<br/>[lint.py]"]
end

subgraph group_delivery["Review and delivery"]
  node_review["Reviewer and mediator<br/>[review.py]"]
  node_revision["Draft revision<br/>[revision.py]"]
  node_finalize["Verdict and finalization<br/>[finalize.py]"]
  node_docx["DOCX renderer<br/>[renderer.py]"]
  node_fallback["Markdown fallback<br/>[fallback.py]"]
end

subgraph group_platform["Runtime foundation"]
  node_cli["mf CLI<br/>[cli.py]"]
  node_state[("Run state<br/>[state_io.py]")]
  node_events[("Audit journal<br/>[events.py]")]
end

subgraph group_capabilities["Additional capabilities"]
  node_brief["Decision brief<br/>[brief.py]"]
  node_probe["MCP availability probe<br/>[probe.py]"]
end

node_user(("Legal question"))
node_model(("Orchestrating model"))
node_databases{{"Legal MCP databases"}}
node_memo["Memo deliverable"]

node_user -->|"poses question"| node_model
node_model -->|"issues commands"| node_cli
node_cli -->|"dispatches workflow"| node_machine
node_machine -->|"requests next action"| node_model
node_machine -->|"runs intake gates"| node_intake
node_machine -->|"selects research route"| node_routing
node_machine -->|"coordinates research"| node_research
node_research -->|"queries authorities"| node_databases
node_routing -->|"selects tools"| node_databases
node_machine -->|"manages source pack"| node_sources
node_sources -.->|"fetches legal material"| node_databases
node_machine -->|"coordinates drafting"| node_draft
node_draft -->|"cites frozen pack"| node_sources
node_machine -->|"checks quotations"| node_quotes
node_machine -->|"tracks provenance"| node_citations
node_machine -->|"checks draft"| node_lint
node_machine -->|"runs review loop"| node_review
node_machine -->|"coordinates revision"| node_revision
node_machine -->|"finalizes verdict"| node_finalize
node_finalize -->|"exports memorandum"| node_docx
node_docx -->|"falls back on failure"| node_fallback
node_docx -->|"writes DOCX and Markdown"| node_memo
node_fallback -->|"writes Markdown"| node_memo
node_machine -->|"reads and writes state"| node_state
node_machine -->|"records run events"| node_events
node_state -->|"journals state writes"| node_events
node_cli -->|"dispatches brief commands"| node_brief
node_cli -->|"dispatches probe commands"| node_probe
node_probe -->|"reports availability"| node_databases

click node_cli "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/cli.py"
click node_machine "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/machine.py"
click node_intake "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/gates.py"
click node_routing "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/routing.py"
click node_research "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/analyze.py"
click node_sources "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/sources.py"
click node_quotes "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/quotes.py"
click node_citations "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/citations.py"
click node_draft "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/draft.py"
click node_lint "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/lint.py"
click node_review "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/review.py"
click node_revision "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/revision.py"
click node_finalize "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/finalize.py"
click node_docx "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/docx/renderer.py"
click node_fallback "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/docx/fallback.py"
click node_state "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/state_io.py"
click node_events "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/events.py"
click node_brief "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/brief.py"
click node_probe "https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/probe.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_machine,node_intake,node_routing,node_research,node_draft toneBlue
class node_sources,node_quotes,node_citations,node_lint,node_databases toneAmber
class node_review,node_revision,node_finalize,node_docx,node_fallback toneMint
class node_cli,node_state,node_events toneRose
class node_brief,node_probe,node_user,node_model,node_memo toneIndigo
```

## Components

### Research workflow

- [Workflow machine](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/machine.py): `scripts/memoforge/machine.py`
- [Intake and gates](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/gates.py): `scripts/memoforge/gates.py`
- [Jurisdiction routing](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/routing.py): `scripts/memoforge/routing.py`
- [Legal research](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/analyze.py): `scripts/memoforge/analyze.py`
- [Memo drafting](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/draft.py): `scripts/memoforge/draft.py`

### Evidence and quality

- [Source registry and freeze](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/sources.py): `scripts/memoforge/sources.py`
- [Quote verification](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/quotes.py): `scripts/memoforge/quotes.py`
- [Citation provenance](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/citations.py): `scripts/memoforge/citations.py`
- [Draft lint](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/lint.py): `scripts/memoforge/lint.py`

### Review and delivery

- [Reviewer and mediator](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/review.py): `scripts/memoforge/review.py`
- [Draft revision](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/revision.py): `scripts/memoforge/revision.py`
- [Verdict and finalization](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/finalize.py): `scripts/memoforge/finalize.py`
- [DOCX renderer](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/docx/renderer.py): `scripts/memoforge/docx/renderer.py`
- [Markdown fallback](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/docx/fallback.py): `scripts/memoforge/docx/fallback.py`

### Runtime foundation

- [mf CLI](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/cli.py): `scripts/memoforge/cli.py`
- [Run state](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/state_io.py): `scripts/memoforge/state_io.py`
- [Audit journal](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/events.py): `scripts/memoforge/events.py`

### Additional capabilities

- [Decision brief](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/brief.py): `scripts/memoforge/brief.py`
- [MCP availability probe](https://github.com/gregmos/memoforge/blob/main/scripts/memoforge/probe.py): `scripts/memoforge/probe.py`

### Other components

- **Legal question**
- **Orchestrating model**
- **Legal MCP databases**
- **Memo deliverable**

## Connections

- Legal question → Orchestrating model: poses question
- Orchestrating model → mf CLI: issues commands
- mf CLI → Workflow machine: dispatches workflow (evidence: `scripts/memoforge/cli.py`)
- Workflow machine → Orchestrating model: requests next action
- Workflow machine → Intake and gates: runs intake gates (evidence: `scripts/memoforge/machine.py`)
- Workflow machine → Jurisdiction routing: selects research route (evidence: `scripts/memoforge/machine.py`)
- Workflow machine → Legal research: coordinates research
- Legal research → Legal MCP databases: queries authorities
- Jurisdiction routing → Legal MCP databases: selects tools (evidence: `scripts/memoforge/routing.py`)
- Workflow machine → Source registry and freeze: manages source pack (evidence: `scripts/memoforge/machine.py`)
- Source registry and freeze → Legal MCP databases: fetches legal material
- Workflow machine → Memo drafting: coordinates drafting
- Memo drafting → Source registry and freeze: cites frozen pack
- Workflow machine → Quote verification: checks quotations
- Workflow machine → Citation provenance: tracks provenance (evidence: `scripts/memoforge/machine.py`)
- Workflow machine → Draft lint: checks draft (evidence: `scripts/memoforge/machine.py`)
- Workflow machine → Reviewer and mediator: runs review loop (evidence: `scripts/memoforge/machine.py`)
- Workflow machine → Draft revision: coordinates revision (evidence: `scripts/memoforge/machine.py`)
- Workflow machine → Verdict and finalization: finalizes verdict (evidence: `scripts/memoforge/machine.py`)
- Verdict and finalization → DOCX renderer: exports memorandum (evidence: `scripts/memoforge/finalize.py`)
- DOCX renderer → Markdown fallback: falls back on failure (evidence: `scripts/memoforge/docx/__init__.py`)
- DOCX renderer → Memo deliverable: writes DOCX and Markdown
- Markdown fallback → Memo deliverable: writes Markdown (evidence: `scripts/memoforge/docx/fallback.py`)
- Workflow machine → Run state: reads and writes state (evidence: `scripts/memoforge/machine.py`)
- Workflow machine → Audit journal: records run events (evidence: `scripts/memoforge/machine.py`)
- Run state → Audit journal: journals state writes (evidence: `scripts/memoforge/state_io.py`)
- mf CLI → Decision brief: dispatches brief commands (evidence: `scripts/memoforge/cli.py`)
- mf CLI → MCP availability probe: dispatches probe commands (evidence: `scripts/memoforge/cli.py`)
- MCP availability probe → Legal MCP databases: reports availability
