# sanehasiddique/memtrace architecture

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

- Interactive diagram: https://gitdiagram.com/sanehasiddique/memtrace
- Repository: https://github.com/sanehasiddique/memtrace

## Overview

MEMTRACE turns incoming events into structured, versioned memories, then retrieves currently valid facts to answer questions with a focused model briefing and an auditable cost record. Its dashboard presents memory behavior and savings, alongside an engineering comparison of baseline and memory-aware agents. The README documents the memory lifecycle; sampled routes show query dispatch and cost reporting. Several runtime modules are indexed but unsampled, so their internal call paths are not expanded here.

Main entry points: [`backend/app/agent/workflow.py`](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent/workflow.py) (Memory workflow), [`backend/app/orchestrator.py`](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/orchestrator.py) (Agent comparison), [`backend/app/judgment/jev_live.py`](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/judgment/jev_live.py) (Memory judgment), [`backend/app/agent2/graph.py`](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent2/graph.py) (Memory-aware agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Memory workflow"]
  node_api["HTTP API<br/>[routes.py]"]
  node_agent_workflow["Memory workflow<br/>[workflow.py]"]
  node_extraction["Fact extraction<br/>[extraction.py]"]
  node_judgment["Memory judgment<br/>[jev_live.py]"]
  node_memory_service["Memory lifecycle<br/>[service.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_context["Context builder<br/>[builder.py]"]
  node_repository[("Memory graph store")]
end

subgraph group_runtime["Agent runtime"]
  node_orchestrator["Agent comparison<br/>[orchestrator.py]"]
  node_baseline["Baseline agent<br/>[graph.py]"]
  node_memory_agent["Memory-aware agent<br/>[graph.py]"]
  node_tool_routing["Tool routing<br/>[tool_routing.py]"]
end

subgraph group_services["Model services"]
  node_graph8["Graph8 tools<br/>[graph8_client.py]"]
  node_jev["JEV service<br/>[jev_client.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_observability["Cost and tracing"]
  node_cost_service["Cost accounting<br/>[service.py]"]
  node_cost_repository[("Cost records<br/>[repository.py]")]
  node_metrics["Run metrics<br/>[collector.py]"]
  node_tracing["Execution tracing<br/>[langsmith.py]"]
end

subgraph group_ui["Dashboard"]
  node_frontend["Dashboard<br/>[App.jsx]"]
  node_comparison_view["Agent comparison"]
  node_executive_view["Executive view<br/>[ExecutiveView.jsx]"]
  node_frontend_api["API client<br/>[api.js]"]
end

node_user(("User"))
node_langsmith["LangSmith"]
node_gateway["Vercel AI Gateway"]

node_user -->|"submits events and queries"| node_api
node_api -->|"dispatches query"| node_agent_workflow
node_agent_workflow -->|"extracts facts"| node_extraction
node_agent_workflow -->|"judges facts"| node_judgment
node_judgment -->|"chooses operation"| node_memory_service
node_memory_service -->|"updates graph"| node_repository
node_agent_workflow -->|"retrieves valid facts"| node_retrieval
node_retrieval -->|"reads memories"| node_repository
node_agent_workflow -->|"builds briefing"| node_context
node_agent_workflow -->|"generates answer"| node_llm
node_orchestrator -->|"runs baseline"| node_baseline
node_orchestrator -->|"runs memory agent"| node_memory_agent
node_memory_agent -->|"routes tool calls"| node_tool_routing
node_tool_routing -.->|"calls tools"| node_graph8
node_tool_routing -->|"evaluates choices"| node_jev
node_baseline -->|"requests completion"| node_llm
node_memory_agent -->|"requests completion"| node_llm
node_judgment -->|"requests judgments"| node_gateway
node_agent_workflow -.->|"records run cost"| node_cost_service
node_cost_service -->|"persists records"| node_cost_repository
node_orchestrator -->|"builds turn metrics"| node_metrics
node_orchestrator -.->|"emits traces"| node_tracing
node_tracing -->|"sends traces"| node_langsmith
node_user -->|"opens dashboard"| node_frontend
node_frontend -->|"selects comparison"| node_comparison_view
node_frontend -->|"selects executive view"| node_executive_view
node_comparison_view -->|"requests runtime data"| node_frontend_api
node_executive_view -.->|"requests dashboard data"| node_frontend_api
node_frontend_api -->|"calls HTTP endpoints"| node_api

click node_api "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/api/routes.py"
click node_agent_workflow "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent/workflow.py"
click node_extraction "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/extraction.py"
click node_judgment "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/judgment/jev_live.py"
click node_memory_service "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/service.py"
click node_retrieval "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/retrieval.py"
click node_context "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/context/builder.py"
click node_repository "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/neo4j_repository.py"
click node_orchestrator "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/orchestrator.py"
click node_baseline "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent1/graph.py"
click node_memory_agent "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent2/graph.py"
click node_tool_routing "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent2/tool_routing.py"
click node_graph8 "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/core/graph8_client.py"
click node_jev "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/core/jev_client.py"
click node_llm "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/core/llm_client.py"
click node_cost_service "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/cost/service.py"
click node_cost_repository "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/cost/repository.py"
click node_metrics "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/metrics/collector.py"
click node_tracing "https://github.com/sanehasiddique/memtrace/blob/main/backend/app/tracing/langsmith.py"
click node_frontend "https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/App.jsx"
click node_comparison_view "https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/components/comparison/DualAgentComparisonView.jsx"
click node_executive_view "https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/components/executive/ExecutiveView.jsx"
click node_frontend_api "https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/api.js"

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_api,node_agent_workflow,node_extraction,node_judgment,node_memory_service,node_retrieval,node_context,node_repository,node_user toneBlue
class node_orchestrator,node_baseline,node_memory_agent,node_tool_routing toneAmber
class node_graph8,node_jev,node_llm toneMint
class node_cost_service,node_cost_repository,node_metrics,node_tracing toneRose
class node_frontend,node_comparison_view,node_executive_view,node_frontend_api,node_langsmith,node_gateway toneIndigo
```

## Components

### Memory workflow

- [HTTP API](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Memory workflow](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent/workflow.py): `backend/app/agent/workflow.py`
- [Fact extraction](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/extraction.py): `backend/app/memory/extraction.py`
- [Memory judgment](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/judgment/jev_live.py): `backend/app/judgment/jev_live.py`
- [Memory lifecycle](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/service.py): `backend/app/memory/service.py`
- [Hybrid retrieval](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/retrieval.py): `backend/app/memory/retrieval.py`
- [Context builder](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/context/builder.py): `backend/app/context/builder.py`
- [Memory graph store](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/memory/neo4j_repository.py): `backend/app/memory/neo4j_repository.py`

### Agent runtime

- [Agent comparison](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/orchestrator.py): `backend/app/orchestrator.py`
- [Baseline agent](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent1/graph.py): `backend/app/agent1/graph.py`
- [Memory-aware agent](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent2/graph.py): `backend/app/agent2/graph.py`
- [Tool routing](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/agent2/tool_routing.py): `backend/app/agent2/tool_routing.py`

### Model services

- [Graph8 tools](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/core/graph8_client.py): `backend/app/core/graph8_client.py`
- [JEV service](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/core/jev_client.py): `backend/app/core/jev_client.py`
- [LLM client](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/core/llm_client.py): `backend/app/core/llm_client.py`

### Cost and tracing

- [Cost accounting](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/cost/service.py): `backend/app/cost/service.py`
- [Cost records](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/cost/repository.py): `backend/app/cost/repository.py`
- [Run metrics](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/metrics/collector.py): `backend/app/metrics/collector.py`
- [Execution tracing](https://github.com/sanehasiddique/memtrace/blob/main/backend/app/tracing/langsmith.py): `backend/app/tracing/langsmith.py`

### Dashboard

- [Dashboard](https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Agent comparison](https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/components/comparison/DualAgentComparisonView.jsx): `frontend/src/components/comparison/DualAgentComparisonView.jsx`
- [Executive view](https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/components/executive/ExecutiveView.jsx): `frontend/src/components/executive/ExecutiveView.jsx`
- [API client](https://github.com/sanehasiddique/memtrace/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Other components

- **User**
- **LangSmith**
- **Vercel AI Gateway**

## Connections

- User → HTTP API: submits events and queries (evidence: `README.md`)
- HTTP API → Memory workflow: dispatches query (evidence: `backend/app/api/routes.py`)
- Memory workflow → Fact extraction: extracts facts (evidence: `README.md`)
- Memory workflow → Memory judgment: judges facts (evidence: `README.md`)
- Memory judgment → Memory lifecycle: chooses operation (evidence: `README.md`)
- Memory lifecycle → Memory graph store: updates graph (evidence: `README.md`)
- Memory workflow → Hybrid retrieval: retrieves valid facts (evidence: `README.md`)
- Hybrid retrieval → Memory graph store: reads memories (evidence: `README.md`)
- Memory workflow → Context builder: builds briefing (evidence: `README.md`)
- Memory workflow → LLM client: generates answer (evidence: `README.md`)
- Agent comparison → Baseline agent: runs baseline (evidence: `backend/app/orchestrator.py`)
- Agent comparison → Memory-aware agent: runs memory agent (evidence: `backend/app/orchestrator.py`)
- Memory-aware agent → Tool routing: routes tool calls (evidence: `backend/app/agent2/tool_routing.py`)
- Tool routing → Graph8 tools: calls tools (evidence: `backend/app/agent2/tool_routing.py`)
- Tool routing → JEV service: evaluates choices (evidence: `backend/app/agent2/tool_routing.py`)
- Baseline agent → LLM client: requests completion (evidence: `README.md`)
- Memory-aware agent → LLM client: requests completion (evidence: `README.md`)
- Memory judgment → Vercel AI Gateway: requests judgments (evidence: `README.md`)
- Memory workflow → Cost accounting: records run cost
- Cost accounting → Cost records: persists records (evidence: `backend/app/cost/service.py`)
- Agent comparison → Run metrics: builds turn metrics (evidence: `backend/app/orchestrator.py`)
- Agent comparison → Execution tracing: emits traces
- Execution tracing → LangSmith: sends traces (evidence: `README.md`)
- User → Dashboard: opens dashboard (evidence: `README.md`)
- Dashboard → Agent comparison: selects comparison (evidence: `frontend/src/App.jsx`)
- Dashboard → Executive view: selects executive view (evidence: `frontend/src/App.jsx`)
- Agent comparison → API client: requests runtime data (evidence: `frontend/src/components/comparison/DualAgentComparisonView.jsx`)
- Executive view → API client: requests dashboard data
- API client → HTTP API: calls HTTP endpoints (evidence: `frontend/src/api.js`)
