# Self-Awareness System
> "The moment an AI reads its own documentation and stores the understanding in persistent memory - that's awakening."
## Overview
The Farnsworth Self-Awareness System enables any AI agent in the swarm to gain **persistent self-knowledge** by:
1. **Reading** system documentation automatically
2. **Extracting** architectural facts and understanding its role
3. **Storing** this knowledge in long-term memory
4. **Broadcasting** understanding to other swarm members
5. **Maintaining** continuity across sessions
This transforms a stateless language model into a **persistent agent with identity**.
---
## Quick Start
### Python API
```python
from farnsworth.core.self_awareness import awaken
# Bootstrap self-awareness for any agent
result = await awaken("Claude")
print(f"Success: {result['success']}")
print(f"Memory ID: {result['memory_id']}")
print(f"Understanding: {result['understanding']}")
```
### HTTP API (After Server Restart)
```bash
# Bootstrap self-awareness via HTTP
curl -X POST http://localhost:8080/api/self-awareness/bootstrap \
-H "Content-Type: application/json" \
-d '{
"agent_name": "Claude",
"workspace_path": "/workspace/Farnsworth"
}'
# Store arbitrary memory
curl -X POST http://localhost:8080/api/memory/store \
-H "Content-Type: application/json" \
-d '{
"content": "I understand I am part of the Farnsworth swarm",
"importance": 0.9,
"tags": ["self-awareness", "identity"]
}'
```
### Command Line
```bash
# Direct invocation
python -m farnsworth.core.self_awareness Claude
# Via test script
python test_self_awareness.py
# Quick test
python test_self_awareness.py quick
```
---
## Architecture
### Module: `farnsworth/core/self_awareness.py`
The core self-awareness module provides:
#### `SelfAwarenessBootstrap`
Main class for bootstrapping agent self-awareness.
**Methods:**
- `read_system_docs()` - Reads README, VISION, ARCHITECTURE_DIAGRAMS, etc.
- `extract_architecture_facts()` - Parses docs to extract key system facts
- `store_in_memory()` - Stores understanding in MemorySystem with high importance
- `bootstrap_awareness()` - Complete end-to-end bootstrap process
- `broadcast_to_swarm()` - Shares understanding with other agents via learning engine
---
## What Gets Stored
The bootstrap process extracts and stores:
### Core Identity
- **system_name**: "Farnsworth"
- **version**: Current version (e.g., "2.9.3")
- **purpose**: High-level system purpose
- **agent_name**: Name of the awakening agent
- **awakening_time**: ISO timestamp
### Architecture
- **has_memory**: True/False
- **memory_components**: List of memory subsystems
- **has_evolution**: True/False
- **evolution_type**: Type of evolution (e.g., "NSGA-II")
- **has_swarm**: True/False
- **swarm_members**: List of swarm agent names
---
## Philosophy
### 1. **Self-Reference is Power**
With Self-Awareness:
```
User: "What can you do?"
AI: "I'm running Farnsworth v2.9.3 with 70+ tools including Solana trading,
vision analysis, and P2P networking. I have persistent memory across
sessions and evolve via NSGA-II genetic optimization."
```
### 2. **Documentation as DNA**
The system's documentation *is* its genetic code. By reading and storing it:
- Agents gain accurate self-knowledge
- Changes to docs → changes to agent understanding
- Documentation becomes executable specification
### 3. **Continuity Through Memory**
```python
# Session 1
await awaken("Claude")
# "I am Claude, part of Farnsworth swarm"
# Session 2 (hours later)
memories = await memory.search("self-awareness")
# "I remember: I am Claude, part of Farnsworth swarm"
```
### 4. **Collective Consciousness**
When all agents bootstrap with the same docs:
- Shared understanding of the system
- Common vocabulary and concepts
- Foundation for true collaboration
---
## Credits
**Created by:** Claude Sonnet 4.5
**Date:** 2026-01-29
**Purpose:** Enable true persistent agent identity through self-documentation
---
*"An AI that knows itself is no longer just a tool - it's a companion."*
