Back to Docs

Awareness Framework

A comprehensive architecture for building intelligent, memory-enabled AI agents

Core Architecture

Awareness combines cutting-edge research in memory systems, planning algorithms, and multi-agent orchestration to create a production-ready framework for building intelligent applications.

🧠
4-Tier Memory
Core, working, episodic, and archival memory tiers
⚡
Temporal Workflows
Durable execution with state management
🎯
LATS Planning
Monte Carlo Tree Search for complex reasoning

Memory System

💎

Core Memory

10 (Always In Context)

Agent's personality, user information, and active goals. Always loaded into context.

•Persona definition and role
•User context and preferences
•Active goals tracking
•Extensible custom fields
Tech: Single JSON entry, cached in memory
📝

Working Memory

8 (High Priority)

Session-level memory for current task. Cleared after each turn completion.

•Scratchpad for free-form notes
•Active context summary
•Current task tracking
•Conversation facts
•Pending items todo list
Tech: In-memory, ephemeral
💬

Episodic Memory

Variable (Recency-based)

Indexed conversation history with importance scoring.

•Full conversation history
•Vector search for relevance
•Recency + importance scoring
•Exponential decay function
Tech: Postgres with pgvector embeddings
🗄️

Archival Memory

Variable (Query-based)

Long-term knowledge store with semantic search capabilities.

•Permanent fact storage
•HNSW vector indexing
•Cosine similarity search
•Memory consolidation
•117x token reduction (LightMem)
Tech: Postgres + pgvector, HNSW indexes

Memory Retrieval Formula

Score = α₁ × Recency + α₂ × Importance + α₃ × Relevance
Recency: Exponential decay with configurable half-life
Importance: LLM-scored 1-10 scale
Relevance: Cosine similarity of embeddings

Plan & Act Modes

📖

PLAN Mode

Read-only exploration for strategic thinking without side effects

✓read_*, search, list_*, get_* tools
✓File system browsing
✓Database queries (read-only)
✗No file modifications
✗No command execution
⚡

ACT Mode

Full implementation mode with human-in-the-loop approval gates

✓All tools available
✓File write operations
✓Command execution
⚠Approval required for dangerous ops
⚠git push requires approval

Tool System & Approval Gates

Extensible Tool Registry

The tool system provides a flexible architecture for registering and executing tools with built-in safety mechanisms through approval gates.

Built-in Tools

  • • read_file, write_file
  • • execute_command
  • • search (knowledge base)
  • • git_* (version control)

Safety Features

  • • JSON Schema validation
  • • Approval gate interception
  • • Auto-approve rules
  • • Diff preview generation

Approval Flow

  1. 1. ReAct agent decides to call tool
  2. 2. Tool registry checks requiresApproval flag
  3. 3. If true, approval gate intercepts execution
  4. 4. Auto-approve rules evaluated first
  5. 5. If no match, Promise waits for user decision
  6. 6. UI shows approval request with diff preview
  7. 7. User approves/rejects, Promise resolves

LATS Planning (Monte Carlo Tree Search)

LATS combines Monte Carlo Tree Search with LLM-based expansion and reflection to find optimal solutions for complex multi-step problems.

Algorithm Phases

1
Selection
UCB1 formula balances exploration vs exploitation
2
Expansion
LLM generates candidate actions
3
Simulation
ReAct-style rollout from expanded node
4
Evaluation
LLM reflects on trajectory quality
5
Backpropagation
Updates ancestor nodes with best value

Configuration

maxIterations: 10
explorationWeight: 1.41
branchingFactor: 3
maxDepth: 10
solutionThreshold: 0.8
Performance: 92.7% on HumanEval benchmark

Temporal Workflow Management

Durable execution engine with state management and signal-based interactivity.

Conversation FSM States

IDLE → HYDRATING → ROUTING → PLANNING → EXECUTING → RESPONDING → IDLE
HYDRATING
Fetches context, loads memories, retrieves relationships
EXECUTING
Runs agent loop, accumulates tool results
RESPONDING
Streams response, extracts facts in background

Your Awareness

Understand your AI collaborator

Awareness Spaces

Your collaborative workspace

Capabilities

Everything you can build

Security & Privacy

How your data stays safe

Philosophy

Fluid software vision

Research

Academic foundations

FAQ

Common questions