# thecodacus/understory architecture

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

- Interactive diagram: https://gitdiagram.com/thecodacus/understory
- Repository: https://github.com/thecodacus/understory

## Overview

Understory is a markdown-based agent memory: users query or change an OKF knowledge bundle through MCP, the web chat, or the CLI; they can also browse its concepts, graph, logs, and run traces. The agent uses configured language models and tools, while deterministic bundle code keeps files conformant. The map includes documented UI and server capabilities, but some implementations (including graph construction and dreaming) were not sampled, so uncertain internal links are omitted.

Main entry points: [`packages/core/src/agent/agent.ts`](https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/agent.ts) (Agent runs), [`packages/web/src/App.tsx`](https://github.com/thecodacus/understory/blob/main/packages/web/src/App.tsx) (Memory browser), [`packages/server/src/app.ts`](https://github.com/thecodacus/understory/blob/main/packages/server/src/app.ts) (HTTP application), [`packages/server/src/mcp/server.ts`](https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/server.ts) (MCP memory tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_memory["OKF Memory"]
  node_bundle[("Markdown bundle<br/>[bundle.ts]")]
  node_frontmatter["Concept format<br/>[frontmatter.ts]"]
  node_search["Concept search<br/>[search.ts]"]
  node_indexing["Bundle indexes<br/>[indexer.ts]"]
  node_graph_build["Memory graph<br/>[graph.ts]"]
  node_conformance["Validation and lint<br/>[validate.ts]"]
  node_knowledge_base["Knowledge base<br/>[knowledge-base.ts]"]
end

subgraph group_agent["Agent Runtime"]
  node_agent_loop["Agent runs<br/>[agent.ts]"]
  node_agent_prompt["System prompt<br/>[system-prompt.ts]"]
  node_agent_tools["Memory tools<br/>[tools.ts]"]
  node_hot_memory["Hot memory<br/>[hot-memory.ts]"]
  node_query_cache["Query cache<br/>[query-cache.ts]"]
  node_traces["Run traces<br/>[trace.ts]"]
  node_providers["Model providers<br/>[index.ts]"]
  node_fallback["Fallback provider<br/>[fallback.ts]"]
end

subgraph group_server["Server Interfaces"]
  node_http_app["HTTP application<br/>[app.ts]"]
  node_auth["Bearer authentication<br/>[auth.ts]"]
  node_profiles["Memory profiles<br/>[profiles.ts]"]
  node_mcp_http["MCP over HTTP<br/>[http.ts]"]
  node_mcp_stdio["MCP over stdio<br/>[stdio.ts]"]
  node_mcp_tools["MCP memory tools<br/>[server.ts]"]
  node_seed["Session seed<br/>[seed.ts]"]
  node_browse_api["Browse API<br/>[browse.ts]"]
  node_chat_api["Streaming chat API<br/>[chat.ts]"]
  node_dreamer["Memory dreamer<br/>[dreamer.ts]"]
end

subgraph group_web["Web UI"]
  node_web_app["Memory browser<br/>[App.tsx]"]
  node_web_api["Browser API client<br/>[api.ts]"]
  node_tree["Bundle tree<br/>[Tree.tsx]"]
  node_concept_view["Concept viewer<br/>[ConceptView.tsx]"]
  node_graph_view["Graph and replay<br/>[GraphView.tsx]"]
  node_log_view["Update log<br/>[LogView.tsx]"]
end

node_user(("Memory user"))
node_mcp_client(("MCP client"))
node_llm{{"LLM endpoint"}}

node_user -->|"invokes tools"| node_mcp_client
node_mcp_client -->|"sends requests"| node_mcp_http
node_mcp_client -->|"starts process"| node_mcp_stdio
node_user -->|"browses memory"| node_web_app
node_agent_loop -->|"creates model"| node_providers
node_providers -->|"calls endpoint"| node_llm
node_agent_loop -->|"builds prompt"| node_agent_prompt
node_agent_loop -->|"registers tools"| node_agent_tools
node_agent_loop -->|"records runs"| node_traces
node_agent_tools -->|"uses memory"| node_hot_memory
node_search -->|"reads concepts"| node_bundle
node_bundle -->|"parses documents"| node_frontmatter
node_http_app -->|"authenticates requests"| node_auth
node_http_app -->|"resolves memory"| node_profiles
node_http_app -->|"mounts route"| node_mcp_http
node_http_app -->|"mounts API"| node_browse_api
node_http_app -->|"mounts API"| node_chat_api
node_mcp_http -->|"creates server"| node_mcp_tools
node_mcp_stdio -->|"creates server"| node_mcp_tools
node_mcp_tools -->|"runs queries"| node_agent_loop
node_mcp_tools -->|"runs mutations"| node_agent_loop
node_mcp_tools -->|"builds overview"| node_seed
node_chat_api -->|"streams chat"| node_agent_loop
node_web_app -->|"loads data"| node_web_api
node_web_app -->|"renders tree"| node_tree
node_web_app -->|"renders concepts"| node_concept_view
node_web_app -->|"renders graph"| node_graph_view
node_web_app -->|"renders log"| node_log_view
node_web_api -->|"requests bundle data"| node_browse_api
node_web_api -->|"requests chat"| node_chat_api

click node_bundle "https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/bundle.ts"
click node_frontmatter "https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/frontmatter.ts"
click node_search "https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/search.ts"
click node_indexing "https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/indexer.ts"
click node_graph_build "https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/graph.ts"
click node_conformance "https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/validate.ts"
click node_knowledge_base "https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/knowledge-base.ts"
click node_agent_loop "https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/agent.ts"
click node_agent_prompt "https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/system-prompt.ts"
click node_agent_tools "https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/tools.ts"
click node_hot_memory "https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/hot-memory.ts"
click node_query_cache "https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/query-cache.ts"
click node_traces "https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/trace.ts"
click node_providers "https://github.com/thecodacus/understory/blob/main/packages/core/src/providers/index.ts"
click node_fallback "https://github.com/thecodacus/understory/blob/main/packages/core/src/providers/fallback.ts"
click node_http_app "https://github.com/thecodacus/understory/blob/main/packages/server/src/app.ts"
click node_auth "https://github.com/thecodacus/understory/blob/main/packages/server/src/auth.ts"
click node_profiles "https://github.com/thecodacus/understory/blob/main/packages/server/src/profiles.ts"
click node_mcp_http "https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/http.ts"
click node_mcp_stdio "https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/stdio.ts"
click node_mcp_tools "https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/server.ts"
click node_seed "https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/seed.ts"
click node_browse_api "https://github.com/thecodacus/understory/blob/main/packages/server/src/api/browse.ts"
click node_chat_api "https://github.com/thecodacus/understory/blob/main/packages/server/src/api/chat.ts"
click node_dreamer "https://github.com/thecodacus/understory/blob/main/packages/server/src/dreamer.ts"
click node_web_app "https://github.com/thecodacus/understory/blob/main/packages/web/src/App.tsx"
click node_web_api "https://github.com/thecodacus/understory/blob/main/packages/web/src/api.ts"
click node_tree "https://github.com/thecodacus/understory/blob/main/packages/web/src/components/Tree.tsx"
click node_concept_view "https://github.com/thecodacus/understory/blob/main/packages/web/src/components/ConceptView.tsx"
click node_graph_view "https://github.com/thecodacus/understory/blob/main/packages/web/src/components/GraphView.tsx"
click node_log_view "https://github.com/thecodacus/understory/blob/main/packages/web/src/components/LogView.tsx"

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_bundle,node_frontmatter,node_search,node_indexing,node_graph_build,node_conformance,node_knowledge_base,node_user,node_mcp_client toneBlue
class node_agent_loop,node_agent_prompt,node_agent_tools,node_hot_memory,node_query_cache,node_traces,node_providers,node_fallback toneAmber
class node_http_app,node_auth,node_profiles,node_mcp_http,node_mcp_stdio,node_mcp_tools,node_seed,node_browse_api,node_chat_api,node_dreamer toneMint
class node_web_app,node_web_api,node_tree,node_concept_view,node_graph_view,node_log_view toneRose
class node_llm toneIndigo
```

## Components

### OKF Memory

- [Markdown bundle](https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/bundle.ts): `packages/core/src/okf/bundle.ts`
- [Concept format](https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/frontmatter.ts): `packages/core/src/okf/frontmatter.ts`
- [Concept search](https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/search.ts): `packages/core/src/okf/search.ts`
- [Bundle indexes](https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/indexer.ts): `packages/core/src/okf/indexer.ts`
- [Memory graph](https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/graph.ts): `packages/core/src/okf/graph.ts`
- [Validation and lint](https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/validate.ts): `packages/core/src/okf/validate.ts`
- [Knowledge base](https://github.com/thecodacus/understory/blob/main/packages/core/src/okf/knowledge-base.ts): `packages/core/src/okf/knowledge-base.ts`

### Agent Runtime

- [Agent runs](https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/agent.ts): `packages/core/src/agent/agent.ts`
- [System prompt](https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/system-prompt.ts): `packages/core/src/agent/system-prompt.ts`
- [Memory tools](https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/tools.ts): `packages/core/src/agent/tools.ts`
- [Hot memory](https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/hot-memory.ts): `packages/core/src/agent/hot-memory.ts`
- [Query cache](https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/query-cache.ts): `packages/core/src/agent/query-cache.ts`
- [Run traces](https://github.com/thecodacus/understory/blob/main/packages/core/src/agent/trace.ts): `packages/core/src/agent/trace.ts`
- [Model providers](https://github.com/thecodacus/understory/blob/main/packages/core/src/providers/index.ts): `packages/core/src/providers/index.ts`
- [Fallback provider](https://github.com/thecodacus/understory/blob/main/packages/core/src/providers/fallback.ts): `packages/core/src/providers/fallback.ts`

### Server Interfaces

- [HTTP application](https://github.com/thecodacus/understory/blob/main/packages/server/src/app.ts): `packages/server/src/app.ts`
- [Bearer authentication](https://github.com/thecodacus/understory/blob/main/packages/server/src/auth.ts): `packages/server/src/auth.ts`
- [Memory profiles](https://github.com/thecodacus/understory/blob/main/packages/server/src/profiles.ts): `packages/server/src/profiles.ts`
- [MCP over HTTP](https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/http.ts): `packages/server/src/mcp/http.ts`
- [MCP over stdio](https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/stdio.ts): `packages/server/src/mcp/stdio.ts`
- [MCP memory tools](https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/server.ts): `packages/server/src/mcp/server.ts`
- [Session seed](https://github.com/thecodacus/understory/blob/main/packages/server/src/mcp/seed.ts): `packages/server/src/mcp/seed.ts`
- [Browse API](https://github.com/thecodacus/understory/blob/main/packages/server/src/api/browse.ts): `packages/server/src/api/browse.ts`
- [Streaming chat API](https://github.com/thecodacus/understory/blob/main/packages/server/src/api/chat.ts): `packages/server/src/api/chat.ts`
- [Memory dreamer](https://github.com/thecodacus/understory/blob/main/packages/server/src/dreamer.ts): `packages/server/src/dreamer.ts`

### Web UI

- [Memory browser](https://github.com/thecodacus/understory/blob/main/packages/web/src/App.tsx): `packages/web/src/App.tsx`
- [Browser API client](https://github.com/thecodacus/understory/blob/main/packages/web/src/api.ts): `packages/web/src/api.ts`
- [Bundle tree](https://github.com/thecodacus/understory/blob/main/packages/web/src/components/Tree.tsx): `packages/web/src/components/Tree.tsx`
- [Concept viewer](https://github.com/thecodacus/understory/blob/main/packages/web/src/components/ConceptView.tsx): `packages/web/src/components/ConceptView.tsx`
- [Graph and replay](https://github.com/thecodacus/understory/blob/main/packages/web/src/components/GraphView.tsx): `packages/web/src/components/GraphView.tsx`
- [Update log](https://github.com/thecodacus/understory/blob/main/packages/web/src/components/LogView.tsx): `packages/web/src/components/LogView.tsx`

### Other components

- **Memory user**
- **MCP client**
- **LLM endpoint**

## Connections

- Memory user → MCP client: invokes tools (evidence: `README.md`)
- MCP client → MCP over HTTP: sends requests (evidence: `README.md`)
- MCP client → MCP over stdio: starts process (evidence: `README.md`)
- Memory user → Memory browser: browses memory (evidence: `README.md`)
- Agent runs → Model providers: creates model (evidence: `packages/core/src/agent/agent.ts`)
- Model providers → LLM endpoint: calls endpoint (evidence: `packages/core/src/providers/index.ts`)
- Agent runs → System prompt: builds prompt (evidence: `packages/core/src/agent/agent.ts`)
- Agent runs → Memory tools: registers tools (evidence: `packages/core/src/agent/agent.ts`)
- Agent runs → Run traces: records runs (evidence: `packages/core/src/agent/agent.ts`)
- Memory tools → Hot memory: uses memory (evidence: `packages/core/src/agent/tools.ts`)
- Concept search → Markdown bundle: reads concepts (evidence: `packages/core/src/okf/search.ts`)
- Markdown bundle → Concept format: parses documents (evidence: `packages/core/src/okf/bundle.ts`)
- HTTP application → Bearer authentication: authenticates requests (evidence: `packages/server/src/app.ts`)
- HTTP application → Memory profiles: resolves memory (evidence: `packages/server/src/app.ts`)
- HTTP application → MCP over HTTP: mounts route (evidence: `packages/server/src/app.ts`)
- HTTP application → Browse API: mounts API (evidence: `packages/server/src/app.ts`)
- HTTP application → Streaming chat API: mounts API (evidence: `packages/server/src/app.ts`)
- MCP over HTTP → MCP memory tools: creates server (evidence: `packages/server/src/mcp/http.ts`)
- MCP over stdio → MCP memory tools: creates server (evidence: `packages/server/src/mcp/stdio.ts`)
- MCP memory tools → Agent runs: runs queries (evidence: `packages/server/src/mcp/server.ts`)
- MCP memory tools → Agent runs: runs mutations (evidence: `packages/server/src/mcp/server.ts`)
- MCP memory tools → Session seed: builds overview (evidence: `packages/server/src/mcp/server.ts`)
- Streaming chat API → Agent runs: streams chat (evidence: `README.md`)
- Memory browser → Browser API client: loads data (evidence: `packages/web/src/App.tsx`)
- Memory browser → Bundle tree: renders tree (evidence: `packages/web/src/App.tsx`)
- Memory browser → Concept viewer: renders concepts (evidence: `packages/web/src/App.tsx`)
- Memory browser → Graph and replay: renders graph (evidence: `packages/web/src/App.tsx`)
- Memory browser → Update log: renders log (evidence: `packages/web/src/App.tsx`)
- Browser API client → Browse API: requests bundle data (evidence: `README.md`)
- Browser API client → Streaming chat API: requests chat (evidence: `README.md`)
