Architecture

Memory Architecture

Norman Agent implements a multi-layer memory system:

Conversation Memory (Short-term)

Stored per userId + chatId pair. Recent messages are injected as system context before each LLM call:

Previous conversation context:
User: What's the weather?
Assistant: It's sunny and 22°C.

Configurable via CONVERSATION_HISTORY_LIMIT (default: 50 messages).

Long-term Memory

Persistent across conversations. Searched semantically when a new user message arrives — relevant memories injected as context:

Relevant long-term knowledge:
User prefers metric units for temperature.

Memory Types

Tool System

Tools are registered via a ToolRegistry with a standard interface:

interface Tool {
  name: string;
  description: string;
  enabled: boolean;
  parameters: JSONSchema;
  execute(params: any, context: ToolContext): Promise<ToolResponse>;
}

Tool Execution Flow

1. Tool schemas injected into system prompt
2. LLM responds with TOOL_CALL:tool_name({"param":"value"})
3. Agent parses calls, executes each tool
4. Results replace tool call patterns in response
5. Follow-up LLM call synthesizes final answer

Built-in Tools

• file_access — Read/write files via Norman Library
• search — Search knowledge base via Norman Search
• memory — Query and store long-term memories
• web_search — External web search

Task System (v1)

Task Lifecycle

pending → running → completed
                  → failed
         → cancelled

Step Dependencies

Steps declare dependencies by title. The execution engine:

1. Identifies all independent steps (no dependencies)
2. Runs them in parallel
3. On completion, unlocks dependent steps
4. Continues until all steps complete or a failure occurs

Agent Assignment

Each task spawns worker agents with roles:

• coordinator — Manages overall task execution
• worker — Executes individual steps
• synthesizer — Combines results into final output