Decision Log

Decisions with reasoning for auditing and learning.

The Decision Log Store records decisions made by agents with reasoning, context, and outcomes. Useful for auditing agent behavior, debugging unexpected outcomes, and building feedback loops.

Aspect	Value
Scope	Per agent
Persistence	Long-term
Default mode	Always (`DecisionLogConfig()`), Agentic (`decision_log=True`)
Supported modes	Always, Agentic

Basic Usage

1from kern.agent import Agent
2from kern.db.postgres import PostgresDb
3from kern.learn import LearningMachine, DecisionLogConfig
4from kern.models.openai import OpenAIChat
5
6agent = Agent(
7    id="my-agent",
8    model=OpenAIChat(id="gpt-4o"),
9    db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
10    learning=LearningMachine(
11        decision_log=DecisionLogConfig(),  # defaults to LearningMode.ALWAYS
12    ),
13    instructions=[
14        "When you make a significant choice, use log_decision to record it.",
15        "Include your reasoning and alternatives you considered.",
16    ],
17)
18
19agent.print_response(
20    "I need help choosing between Python and JavaScript for web scraping.",
21    session_id="session_1",
22)
23
24# View logged decisions
25lm = agent.get_learning_machine()
26lm.decision_log_store.print(agent_id="my-agent", limit=5)

Agentic Mode

The agent receives tools to explicitly log decisions.

1from kern.learn import LearningMachine, LearningMode, DecisionLogConfig
2
3agent = Agent(
4    id="my-agent",
5    model=OpenAIChat(id="gpt-4o"),
6    db=db,
7    learning=LearningMachine(
8        decision_log=DecisionLogConfig(mode=LearningMode.AGENTIC),
9    ),
10)

Available tools: log_decision, record_outcome, search_decisions

The agent decides when a decision is significant enough to log.

Always Mode

Tool calls are automatically logged as decisions.

1from kern.learn import LearningMachine, LearningMode, DecisionLogConfig
2
3agent = Agent(
4    id="my-agent",
5    model=OpenAIChat(id="gpt-4o"),
6    db=db,
7    learning=LearningMachine(
8        decision_log=DecisionLogConfig(mode=LearningMode.ALWAYS),
9    ),
10    tools=[DuckDuckGoTools()],
11)
12
13agent.print_response("What are the latest developments in AI agents?")
14# Tool calls are automatically recorded as decisions

Tradeoff: logs every tool call, may generate noise.

Data Model

Field	Description
`id`	Unique identifier (e.g., "dec_abc123")
`decision`	What was decided
`reasoning`	Why this decision was made
`decision_type`	Category: tool_selection, response_style, clarification
`context`	The situation that required a decision
`alternatives`	Other options considered
`confidence`	How confident (0.0 to 1.0)
`outcome`	What happened as a result
`outcome_quality`	Was it good, bad, or neutral
`created_at`	When the decision was made

Recording Outcomes

Update decisions with what actually happened to build feedback loops:

1lm = agent.get_learning_machine()
2
3# Via store directly
4lm.decision_log_store.update_outcome(
5    decision_id="dec_abc123",
6    outcome="User was satisfied with Python recommendation",
7    outcome_quality="good",
8)

Or the agent can use the record_outcome tool during conversation.

Accessing Decisions

1lm = agent.get_learning_machine()
2
3# Search decisions
4decisions = lm.decision_log_store.search(
5    agent_id="my-agent",
6    decision_type="tool_selection",
7    days=7,
8    limit=10,
9)
10
11for d in decisions:
12    print(f"{d.decision}: {d.reasoning}")
13
14# Debug output
15lm.decision_log_store.print(agent_id="my-agent", limit=5)

Context Injection

Recent decisions are injected into the system prompt:

1<decision_log>
2Recent decisions:
3
4- **Recommended Python over JavaScript**
5  Reasoning: Web scraping libraries are more mature in Python
6  Outcome: User was satisfied
7
8- **Used web search for current info**
9  Reasoning: Question about recent developments requires fresh data
10</decision_log>

Decision Types

Common categories for organizing decisions:

Type	When to use
`tool_selection`	Choosing which tool to call
`response_style`	Deciding how to format or phrase response
`clarification`	Choosing to ask for more info
`escalation`	Deciding to defer to human
`approach`	Choosing between solution strategies

Use Cases

Auditing: Review what decisions agents made and why
Debugging: Understand unexpected behavior by examining reasoning
Learning: Analyze outcome patterns to improve agent instructions
Feedback loops: Record outcomes to identify successful patterns