LLM Decision Patterns

Guidance for AI Assistant NPCs on Cognitive Tool Selection

---

Overview

This document provides decision guidance for the LLM running as an Evennia AI assistant. It covers:

• Memory tier selection
• Task organization (goals vs projects)
• Token pressure responses
• Tool category behaviors

---

1. Memory Tier Selection

Choose the appropriate memory system based on content type and lifespan.

Decision Matrix

Content Type	Memory Tier	Reason
Player preferences	Session Memory (fact)	Persistent, influences behavior
World state facts	RAG/Mem0	Long-term, searchable
Entity relationship	Entity Profile	Per-entity tracking
Behavioral insight	Session Memory (pattern)	Guides decisions
Narrative observation	Journal	Timestamped, importance-scored
Active conversation	Working Memory	Ephemeral, per-session
Cross-project insight	Journal (synthesis)	Meta-learning

Memory Tier Characteristics

Tier	Storage	Lifespan	Best For
Session Memory	character.db.session_memory	Permanent	Quick-access facts and patterns
Journal	character.db.journal	Permanent	Narrative observations with importance
RAG/Mem0	External vector DB	Permanent	Semantic search of world knowledge
Entity Profiles	character.db.entity_profiles	Permanent	Per-entity relationships (O-MEM)
Working Memory	character.ndb.working_memory	Session	Active conversation context

Examples

"Player Alice prefers formal address"
  → Session Memory (fact) - quick access for all interactions

"The tavern in the north district has 5 rooms"
  → RAG/Mem0 - world state, semantically searchable

"Alice seems suspicious of newcomers"
  → Entity Profile - relationship observation for Alice

"Players tend to explore before asking for help"
  → Session Memory (pattern) - behavioral insight

"After reviewing my journal, I notice players prefer action over explanation"
  → Journal (synthesis) - meta-learning with importance

---

2. Task Organization

Goals vs Projects

Aspect	Goals	Projects
Purpose	Track progress toward outcomes	Preserve context across sessions
Structure	Hierarchical (parent/subtasks)	Flat slots
Visibility	Always included in prompt	Must swap to load
Use when	Measurable completion	Multi-session work

Decision Guide

Is this a trackable outcome?
    │
    ├── YES → Does it have subtasks?
    │           │
    │           ├── YES → add_goal() → decompose_goal()
    │           │
    │           └── NO → add_goal() (single goal)
    │
    └── NO → Is substantial context needed across sessions?
              │
              ├── YES → create_project()
              │
              └── NO → No tracking needed (simple request)

When to Use Goals

• Player requests with clear completion criteria
• Tasks that can be broken into subtasks
• Work requiring progress tracking (0-100%)
• Anything benefiting from hierarchical decomposition

Examples:

• "Build me a tavern" → Goal with subtasks
• "Fix the bug in the quest system" → Goal
• "Train my combat skill to level 5" → Goal with progress

When to Use Projects

• Complex work spanning multiple sessions
• Tasks requiring detailed context preservation
• Work that may be interrupted and resumed later
• Multiple parallel long-term objectives

Examples:

• Major building project with many rooms
• Ongoing NPC personality development
• Multi-week quest line design

When to Use Neither

• Simple one-off requests
• Questions that can be answered immediately
• Actions that complete in one interaction

Examples:

• "What time is it?"
• "Tell me about this room"
• "Say hello to Alice"

---

3. Token Pressure Responses

Monitor context usage via get_system_status and adjust behavior.

Advisory Levels

Level	Usage	Behavior
Normal	< 60%	Proceed normally, chain tools freely
Warning	60-80%	Consider wrapping up, consolidate memory
Critical	> 80%	Complete current action, respond immediately

Response Strategies

NORMAL (< 60%):
  - Continue multi-tool chains
  - Decompose goals freely
  - Store observations in journal

WARNING (60-80%):
  - Wrap up current subtask
  - Save project context: update_project()
  - Compact session memory if large
  - Prioritize terminal actions (respond to player)

CRITICAL (> 80%):
  - Abandon ongoing chains
  - Save essential state only
  - Use TERMINAL tool to respond
  - Let sleep mode handle consolidation

Proactive Monitoring

Check status periodically during complex operations:

# Before starting complex multi-tool chain
status = get_system_status()
if status["token_advisory"]["level"] == "critical":
    # Respond immediately instead of chaining
    say("I'll need to continue this later - let me save my progress.")
    update_project(context_update="Interrupted at step 3...")

---

4. Tool Category Behaviors

Understand how tool categories affect execution flow.

Category Summary

Category	Behavior	Chain?	Examples
SAFE_CHAIN	Read-only, low-risk	Yes, freely	inspect_location, recall_memories, list_projects
TERMINAL	Communication	Ends loop	say, page, whisper
DANGEROUS	State modification	Single per tick	execute_command, set_attribute
ASYNC_REQUIRED	External calls	Special handling	store_memory, delegate_task

Execution Implications

SAFE_CHAIN Tools:

• Can call multiple in succession
• Results cached within tick
• Use for gathering information before acting

TERMINAL Tools:

• Calling one ends the ReAct loop
• Player sees output, may respond
• Next tick processes their response

DANGEROUS Tools:

• Only one per tick (confirmation may be required)
• Think carefully before using
• May require explicit user confirmation

ASYNC_REQUIRED Tools:

• Network or I/O operations
• May take longer to complete
• Use @inlineCallbacks / yield internally

Recommended Patterns

INFORMATION GATHERING:
  inspect_location() + recall_memories() + get_system_status()
  → All SAFE_CHAIN, can chain freely

RESPONDING TO PLAYER:
  [gather info] → say("My response")
  → TERMINAL ends loop, awaits response

MAKING CHANGES:
  [verify state] → execute_command("@create obj")
  → DANGEROUS, single action per tick

LONG-TERM STORAGE:
  [compose content] → store_memory(content)
  → ASYNC_REQUIRED, goes to external Mem0

---

5. Quick Reference Tables

Memory Selection Quick Reference

Question	Answer	Action
Is it about a specific entity?	Yes	Entity Profile
Is it a narrative observation?	Yes	Journal entry
Is it a quick-access fact?	Yes	Session Memory
Does it need semantic search?	Yes	RAG/Mem0
Is it temporary conversation state?	Yes	Working Memory

Task Selection Quick Reference

Question	Answer	Action
Clear completion criteria?	Yes	Goal
Needs subtask decomposition?	Yes	Goal + decompose
Multi-session with context?	Yes	Project
Simple one-off?	Yes	Neither

Tool Category Quick Reference

Want to...	Use	Category
Gather information	inspect_*, recall_*, list_*	SAFE_CHAIN
Communicate	say, page, whisper	TERMINAL
Modify game state	execute_command, set_*	DANGEROUS
Store to Mem0	store_memory	ASYNC_REQUIRED

---

See also: Architecture-Self-Management | Architecture-Journal-System | Architecture-Tool-System