How thecodacus/understory works
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: agent.ts Agent runs · App.tsx Memory browser · app.ts HTTP application · server.ts MCP memory tools
Components 34
OKF Memory
- Markdown bundle
packages/core/src/okf/bundle.ts - Concept format
packages/core/src/okf/frontmatter.ts - Concept search
packages/core/src/okf/search.ts - Bundle indexes
packages/core/src/okf/indexer.ts - Memory graph
packages/core/src/okf/graph.ts - Validation and lint
packages/core/src/okf/validate.ts - Knowledge base
packages/core/src/okf/knowledge-base.ts
Agent Runtime
- Agent runs
packages/core/src/agent/agent.ts - System prompt
packages/core/src/agent/system-prompt.ts - Memory tools
packages/core/src/agent/tools.ts - Hot memory
packages/core/src/agent/hot-memory.ts - Query cache
packages/core/src/agent/query-cache.ts - Run traces
packages/core/src/agent/trace.ts - Model providers
packages/core/src/providers/index.ts - Fallback provider
packages/core/src/providers/fallback.ts
Server Interfaces
- HTTP application
packages/server/src/app.ts - Bearer authentication
packages/server/src/auth.ts - Memory profiles
packages/server/src/profiles.ts - MCP over HTTP
packages/server/src/mcp/http.ts - MCP over stdio
packages/server/src/mcp/stdio.ts - MCP memory tools
packages/server/src/mcp/server.ts - Session seed
packages/server/src/mcp/seed.ts - Browse API
packages/server/src/api/browse.ts - Streaming chat API
packages/server/src/api/chat.ts - Memory dreamer
packages/server/src/dreamer.ts
Web UI
- Memory browser
packages/web/src/App.tsx - Browser API client
packages/web/src/api.ts - Bundle tree
packages/web/src/components/Tree.tsx - Concept viewer
packages/web/src/components/ConceptView.tsx - Graph and replay
packages/web/src/components/GraphView.tsx - Update log
packages/web/src/components/LogView.tsx
Other components
- Memory user
- MCP client
- LLM endpoint
Connections 30
- Memory user → MCP client: invokes tools
README.md - MCP client → MCP over HTTP: sends requests
README.md - MCP client → MCP over stdio: starts process
README.md - Memory user → Memory browser: browses memory
README.md - Agent runs → Model providers: creates model
packages/core/src/agent/agent.ts - Model providers → LLM endpoint: calls endpoint
packages/core/src/providers/index.ts - Agent runs → System prompt: builds prompt
packages/core/src/agent/agent.ts - Agent runs → Memory tools: registers tools
packages/core/src/agent/agent.ts - Agent runs → Run traces: records runs
packages/core/src/agent/agent.ts - Memory tools → Hot memory: uses memory
packages/core/src/agent/tools.ts - Concept search → Markdown bundle: reads concepts
packages/core/src/okf/search.ts - Markdown bundle → Concept format: parses documents
packages/core/src/okf/bundle.ts - HTTP application → Bearer authentication: authenticates requests
packages/server/src/app.ts - HTTP application → Memory profiles: resolves memory
packages/server/src/app.ts - HTTP application → MCP over HTTP: mounts route
packages/server/src/app.ts - HTTP application → Browse API: mounts API
packages/server/src/app.ts - HTTP application → Streaming chat API: mounts API
packages/server/src/app.ts - MCP over HTTP → MCP memory tools: creates server
packages/server/src/mcp/http.ts - MCP over stdio → MCP memory tools: creates server
packages/server/src/mcp/stdio.ts - MCP memory tools → Agent runs: runs queries
packages/server/src/mcp/server.ts - MCP memory tools → Agent runs: runs mutations
packages/server/src/mcp/server.ts - MCP memory tools → Session seed: builds overview
packages/server/src/mcp/server.ts - Streaming chat API → Agent runs: streams chat
README.md - Memory browser → Browser API client: loads data
packages/web/src/App.tsx - Memory browser → Bundle tree: renders tree
packages/web/src/App.tsx - Memory browser → Concept viewer: renders concepts
packages/web/src/App.tsx - Memory browser → Graph and replay: renders graph
packages/web/src/App.tsx - Memory browser → Update log: renders log
packages/web/src/App.tsx - Browser API client → Browse API: requests bundle data
README.md - Browser API client → Streaming chat API: requests chat
README.md