### Install Dependencies

Source: https://github.com/kodareken/rethinking-ai/blob/main/Pi.md

Installs all project dependencies using npm. This command should be run before other development commands.

```bash
npm install
```

--------------------------------

### Set Up a Virtual Environment and Install Dependencies

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Use this bash script to create a clean virtual environment and install project dependencies from requirements files. This is useful for resolving dependency conflicts.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements2.txt
```

--------------------------------

### Start WebUI Server

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Execute this command to launch the Agent Zero web interface.

```bash
python run_ui.py
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Run these commands individually to install the necessary Python packages for the project.

```bash
pip install -r requirements.txt
```

```bash
pip install -r requirements2.txt
```

--------------------------------

### Example of Semantic Map Structure

Source: https://github.com/kodareken/rethinking-ai/blob/main/semantic-map-vs-raw-trees.md

Demonstrates a semantic map with added descriptions for folders, providing intent and context for AI agents.

```bash
├── src/               # Frontend (Svelte 5 / TS) - Target: Platform Agnostic UI  
│   ├── components/    # Visual Organs (Capture, Search, Settings)  
├── src-tauri/         # Backend (Rust) - The System Interface  
│   ├── src/ai/        # Perception (GPU detection, Ollama, Kokoro)
```

--------------------------------

### Example of Folder-Only Tree Structure

Source: https://github.com/kodareken/rethinking-ai/blob/main/semantic-map-vs-raw-trees.md

Illustrates a basic folder structure without semantic meaning, highlighting the 'Semantic Void' for AI reasoning.

```bash
├── src/  
│   ├── components/  
│   ├── stores/  
│   └── lib/  
```

--------------------------------

### Agent Design Heuristics (Python)

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Use this function as an anti-bloat filter before writing agent code. It guides decisions on agent type, state management, tool definition, success state definition, and risk-based guardrails.

```python
def design_agent(task_description: str):
    """
    Anti-Bloat Filter: Run this before writing any agent code.
    """

    # 1. Is this a chatbot or a worker?
    # If doing work (move files, scrape web, send email):
    # Use "Fire-and-Forget", NOT conversational loops

    # 2. Do we need a Class?
    # If agent has no state, write a function, not a class

    # 3. Do we need a Tool Definition?
    # BAD: Defining tool `list_files(directory)`
    # GOOD: Just run `ls -la` in subprocess
    # RULE: If it exists in Shell/OS, it is NOT a tool. It is native context.

    # 4. Define Success State PROGRAMMATICALLY
    # BAD (vague): "The agent should organize my files"
    # GOOD (concrete): "Success = All .png in /Images AND Desktop count == 0"

    def verify_success() -> bool:
        """Every agent MUST have programmatic verification"""
        png_in_images = all(f.endswith('.png') for f in os.listdir('/Images'))
        desktop_empty = len(os.listdir('~/Desktop')) == 0
        return png_in_images and desktop_empty

    # 5. Classify Risk Level and inject guardrails
    RISK_LEVELS = {
        "L1_READ_ONLY": {
            "actions": ["reading files", "browsing web", "checking logs"],
            "guardrail": None  # Run autonomously
        },
        "L2_REVERSIBLE": {
            "actions": ["moving files", "creating folders", "drafting"],
            "guardrail": "verification_loop"  # Did it move correctly?
        },
        "L3_DESTRUCTIVE": {
            "actions": ["deleting files", "sending emails", "git push", "spending money"],
            "guardrail": "human_in_the_loop"  # Requires input("Proceed? [y/n]")
        }
    }

    return design
```

--------------------------------

### JIT Context Compiler (Go)

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Compile context Just-In-Time using Go's text/template for dynamic prompt generation. This avoids large static prompt files and reduces token costs by injecting live state.

```go
// JIT Context Compiler using Go's text/template

import "text/template"

// Base skeleton: minimal system.md with core AI truths
const baseTemplate = `
You are an AI agent. Core truths:
- Do not assume. Investigate first.
- Read files before editing.
- The live system is the truth.

{{.RoleInjection}}

Current State:
{{.LiveState}}
`

type ContextCompiler struct {
    tmpl *template.Template
}

func (c *ContextCompiler) Compile(agentRole string, locks map[string]string) string {
    data := struct {
        RoleInjection string
        LiveState     string
    }{
        // Role injection from YAML config (Frontend, DB Admin, etc.)
        // Injects only the tools needed for that role
        RoleInjection: c.loadRole(agentRole),

        // Live injection: exact current state of file locks
        // and recent colleague actions
        LiveState: c.formatLocks(locks),
    }

    var buf bytes.Buffer
    c.tmpl.Execute(&buf, data)
    return buf.String()
}

// Benefits:
// - No 100+ bloated prompt files
// - Context compiled right before hitting LLM API
// - Drastically reduced token costs
// - Prevents "Context Bloat"

```

--------------------------------

### Run Pi from Sources

Source: https://github.com/kodareken/rethinking-ai/blob/main/Pi.md

Allows running the pi tool directly from the source code, executable from any directory within the project.

```bash
./pi-test.sh
```

--------------------------------

### Semantic vs Raw File Mapping

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Comparison of raw file tree structures versus semantic maps for efficient context management.

```markdown
# BAD: Raw automated file tree (creates false confidence)
├── src/
│   ├── components/
│   │   ├── Camera.svelte
│   │   ├── Search.svelte
│   │   └── Settings.svelte
│   ├── stores/
│   └── lib/

# The AI sees "Camera.svelte" and ASSUMES it knows what it does
# based on training data. It skips using read_file and hallucinates.

# GOOD: Semantic map (AGENTS.md style)
├── src/               # Frontend (Svelte 5 / TS) - Target: Platform Agnostic UI
│   ├── components/    # Visual Organs (Capture, Search, Settings)
├── src-tauri/         # Backend (Rust) - The System Interface
│   ├── src/ai/        # Perception (GPU detection, Ollama, Kokoro)

# Benefits:
# 1. Provides INTENT, not just paths ("Visual Organs" vs "components")
# 2. Forces tool usage - files are excluded, so AI MUST run ls/read
# 3. Maximum context compression - ~100 tokens vs thousands
# 4. Engineers "Semantic Void" that forces active discovery
```

--------------------------------

### Manage Frontend State with Alpine.js

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Utilize Alpine.js stores with init, onOpen, and cleanup lifecycle hooks for reactive state management.

```javascript
import { createStore } from "/js/AlpineStore.js";

export const store = createStore("myStore", {
    // Reactive state
    items: [],
    loading: false,
    error: null,

    // Global setup - runs once when store is created
    init() {
        console.log("Store initialized");
        this.loadInitialData();
    },

    // Mount setup - runs when component using store mounts
    onOpen() {
        this.subscribeToWebSocket();
    },

    // Unmount cleanup - runs when component unmounts
    cleanup() {
        this.unsubscribeFromWebSocket();
    },

    // Actions
    async loadInitialData() {
        this.loading = true;
        try {
            const response = await fetch("/api/items");
            this.items = await response.json();
        } catch (e) {
            this.error = e.message;
        } finally {
            this.loading = false;
        }
    }
});

// Usage in HTML with store gating pattern
// <div x-data>
//   <template x-if="$store.myStore">
//     <div x-init="$store.myStore.onOpen()">
//       <template x-for="item in $store.myStore.items">
//         <div x-text="item.name"></div>
//       </template>
//     </div>
//   </template>
// </div>
```

--------------------------------

### Create Alpine.js Store

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Use createStore from /js/AlpineStore.js to register new stores.

```javascript
import { createStore } from "/js/AlpineStore.js";

export const store = createStore("myStore", {
    items: [],
    init() { /* global setup */ },
    onOpen() { /* mount setup */ },
    cleanup() { /* unmount cleanup */ }
});
```

--------------------------------

### Run Tests

Source: https://github.com/kodareken/rethinking-ai/blob/main/Pi.md

Executes all tests in the repository. LLM-dependent tests are skipped unless API keys are configured.

```bash
./test.sh
```

--------------------------------

### Execute Code in Shadow Filesystem Sandbox

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Uses in-memory filesystems to allow agents to test code changes without modifying the actual disk until verification succeeds.

```go
import (
    "io/fs"
    "testing/fstest"
)

// Shadow FS: In-memory copy of locked files for safe exploration
type ShadowFS struct {
    base   fs.FS
    shadow fstest.MapFS
}

func (e *Engine) ExecuteInSandbox(agentID string, action func(fs.FS) error) error {
    // 1. Create Shadow FS - in-memory copy of relevant files
    shadow := e.createShadow(agentID)

    // 2. Agent writes code and runs tests against Shadow FS
    err := action(shadow)

    if err != nil {
        // FAILURE: Shadow FS wiped, real disk untouched
        // Agent receives error logs to try again
        e.wipeShadow(agentID)
        return fmt.Errorf("sandbox execution failed: %w", err)
    }

    // 3. SUCCESS: Compile passed, tests passed
    // Merge Shadow FS into real OS disk
    return e.mergeShadow(agentID, shadow)
}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Overview of the file and directory layout for the Agent Zero project.

```tree
/
├── agent.py              # Core Agent and AgentContext definitions
├── initialize.py         # Framework initialization logic
├── models.py             # LLM provider configurations
├── run_ui.py             # WebUI server entry point
├── api/                  # API Handlers (ApiHandler subclasses) + WsHandler subclasses (ws_*.py)
├── extensions/           # Backend lifecycle extensions
├── helpers/              # Shared Python utilities (plugins, files, etc.)
├── tools/                # Agent tools (Tool subclasses)
├── webui/
│   ├── components/       # Alpine.js components
│   ├── js/               # Core frontend logic (modals, stores, etc.)
│   └── index.html        # Main UI shell
├── usr/                  # User data directory (isolated from core)
│   ├── plugins/          # Custom user plugins
│   ├── settings.json     # User-specific configuration
│   └── workdir/          # Default agent workspace
├── plugins/              # Core system plugins
├── agents/               # Agent profiles (prompts and config)
├── prompts/              # System and message prompt templates
├── knowledge/
│   └── main/about/       # Agent self-knowledge (indexed into vector DB for runtime recall)
│       ├── identity.md           # Philosophy, principles, project context
│       ├── architecture.md       # Agent loop, memory pipeline, multi-agent, extensions
│       ├── capabilities.md       # Detailed capabilities and limitations
│       ├── configuration.md      # LLM roles, providers, profiles, plugins, settings
│       └── setup-and-deployment.md  # Docker deployment, updates, troubleshooting
└── tests/                # Pytest suite

```

--------------------------------

### Implement Alpine.js Store Gating

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Wrap store-dependent content in a template to ensure the store is initialized before access.

```html
<div x-data>
  <template x-if="$store.myStore">
    <div x-init="$store.myStore.onOpen()">...</div>
  </template>
</div>
```

--------------------------------

### Build All Packages

Source: https://github.com/kodareken/rethinking-ai/blob/main/Pi.md

Compiles all packages within the monorepo. This is a prerequisite for commands like `npm run check` which rely on compiled output.

```bash
npm run build
```

--------------------------------

### Integrate FAISS Memory Engine

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Use the MemoryEngine to save and retrieve context-aware memories via semantic similarity search.

```python
# Memory tools available to the agent:
# - memory_save: Store memories in vector database
# - memory_load: Retrieve relevant memories by similarity search
# - memory_delete: Remove specific memories
# - memory_forget: Bulk forget operations
# - behaviour_adjustment: Learn from failures

# Core memory engine usage (helpers/memory.py)
from helpers.memory import MemoryEngine

async def use_memory(context):
    engine = MemoryEngine(context)

    # Save a memory with embedding
    await engine.save(
        content="User prefers TypeScript over JavaScript",
        metadata={"type": "preference", "confidence": 0.9}
    )

    # Retrieve relevant memories by semantic similarity
    memories = await engine.search(
        query="What programming language does the user like?",
        top_k=5,
        threshold=0.7
    )

    # Memory is stored per subdirectory for scoped contexts
    # Supports different memory subdirectories for agent/project isolation
```

--------------------------------

### Define Agent Tools

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Create Tool subclasses to provide sensory capabilities. The ShellTool pattern leverages native Bash fluency for general-purpose execution.

```python
from helpers.tool import Tool, Response

class MyTool(Tool):
    """Tools derive from Tool base class in helpers/tool.py"""

    async def execute(self, **kwargs) -> Response:
        """
        Execute tool logic and return structured response.

        Response parameters:
        - message: Result text shown to the agent
        - break_loop: True to stop the agent loop after this tool
        """
        try:
            # Tool implementation
            file_path = kwargs.get("path")
            content = await self.read_file(file_path)

            return Response(
                message=f"File contents:\n{content}",
                break_loop=False  # Continue agent loop
            )
        except FileNotFoundError:
            return Response(
                message=f"Error: File {file_path} not found. Use ls to discover files.",
                break_loop=False
            )

# The "God Tool" pattern: prefer shell_exec over 20 specific tools
# The AI already understands Bash - let it use native fluency
class ShellTool(Tool):
    async def execute(self, command: str, **kwargs) -> Response:
        result = await self.run_shell(command)
        return Response(message=result, break_loop=False)
```

--------------------------------

### Define a Custom Tool in Python

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Implement a custom tool by inheriting from the base Tool class and defining the execute method. Ensure the execute method returns a Response object.

```python
from helpers.tool import Tool, Response

class MyTool(Tool):
    async def execute(self, **kwargs):
        # Tool logic
        return Response(message="Success", break_loop=False)
```

--------------------------------

### Check Code Quality

Source: https://github.com/kodareken/rethinking-ai/blob/main/Pi.md

Performs linting, formatting, and type checking across all packages. Requires `npm run build` to be executed first.

```bash
npm run check
```

--------------------------------

### Implement System 1 and System 2 Classes

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Defines the structure for the fast subconscious System 1 and the deep reasoning System 2 models.

```python
class System1:
    """Fast, cheap, always-on subconscious"""

    def __init__(self, model="local-8b"):
        self.model = model  # Fast, cheap model

    async def preprocess(self, user_input: str) -> dict:
        """Filter noise, retrieve relevant memories, format for System 2"""
        memories = await self.vector_search(user_input)
        formatted = await self.semantic_format(user_input, memories)
        return {"input": formatted, "memories": memories}

    async def monitor_thoughts(self, thought_stream: str) -> str | None:
        """Monitor System 2's <thought> blocks for mistakes"""
        if self.detects_collision(thought_stream):
            return self.load_skill("collision_avoidance")
        if self.detects_known_mistake(thought_stream):
            return self.load_skill("error_correction")
        return None

class System2:
    """Deep reasoning conscious worker"""

    def __init__(self, model="claude-3-opus"):
        self.model = model  # Heavy reasoning model

    async def reason(self, preprocessed: dict) -> str:
        """Deep reasoning on refined, relevant data from System 1"""
        return await self.llm_call(preprocessed["input"])
```

--------------------------------

### Implement File-Level Locking in Go

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Uses a mutex to manage file access between concurrent agents, preventing race conditions during write operations.

```go
func (e *Engine) WriteFile(agentID string, path string, content string) error {
    e.mu.Lock()
    defer e.mu.Unlock()

    // Check if file is locked by another agent
    if holder, locked := e.locks[path]; locked && holder != agentID {
        // Deny write, return context injection for agent to pivot
        return fmt.Errorf("CRITICAL: %s is locked by Agent %s. Do not overwrite.", path, holder)
    }

    // Grant lock and proceed
    e.locks[path] = agentID
    return os.WriteFile(path, []byte(content), 0644)
}
```

--------------------------------

### Implement AST-Aware Semantic Locking

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Allows multiple agents to edit different functions within the same file by locking specific AST nodes instead of the entire file.

```go
import (
    "go/ast"
    "go/parser"
    "go/token"
    "sync"
)

type SemanticLock struct {
    mu    sync.RWMutex
    locks map[string]string // node identifier -> agent ID
}

func (sl *SemanticLock) LockNode(agentID, filePath, funcName string) error {
    sl.mu.Lock()
    defer sl.mu.Unlock()

    nodeKey := fmt.Sprintf("%s::%s", filePath, funcName)

    if holder, locked := sl.locks[nodeKey]; locked {
        return fmt.Errorf("func %s locked by %s", funcName, holder)
    }

    sl.locks[nodeKey] = agentID
    return nil
}
```

--------------------------------

### System Prompt Framing

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Contrast between negative rule enforcement and positive knowledge-based framing to improve agent reliability.

```python
# BAD: Rule enforcement through negation
system_prompt = """
DO NOT hallucinate.
DO NOT make assumptions.
DO NOT be lazy.
DO NOT forget instructions.
"""

# GOOD: Pass knowledge and understanding
system_prompt = """
You are a prediction machine operating on tokens. Your training data is stale.
The live system is the truth - investigate, read files, and run tools to discover
reality rather than relying on assumed knowledge.

When verification is limited:
- Map what is certain vs uncertain
- Propose the smallest test that gives the most information
- Use the real environment (files, logs, output) as the source of truth

An agent that understands the consequences of failure will self-verify.
"""
```

--------------------------------

### System 1: Subconscious (Python)

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Represents the fast, cheap, always-on utility model (System 1) in a biomimetic architecture. Handles tasks like formatting text, retrieving memories, managing skills, and alerting on mistakes.

```python
# System 1: The Subconscious (Fast Secretary)
# - Cheap, always-on utility model (e.g., 8B local)
# - Handles: format text, retrieve memories, manage skills, alert on mistakes

```

--------------------------------

### Agent Action Loop

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

A behavioral loop that forces agents to hypothesize, verify through tools, and adapt based on observations.

```python
# The Anti-Assumption Protocol (behavioral loop):
async def agent_action_loop(agent, task):
    """Every action follows: Hypothesize -> Verify -> Adapt"""

    # 1. Form hypothesis
    hypothesis = await agent.reason(task)

    # 2. Formulate verification command
    verification = await agent.plan_verification(hypothesis)
    # Examples: grep, ls, cat, git status, run tests

    # 3. Execute and observe (NOT predict)
    result = await agent.execute_tool(verification)

    # 4. Adapt based strictly on the output
    next_action = await agent.adapt(hypothesis, result)

    return next_action
```

--------------------------------

### Silent Output Protocol (Python)

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Implement a silent output protocol to minimize cognitive friction by outputting only structured intent, errors, or results. This avoids verbose conversational output and saves tokens.

```python
# BAD: Verbose agent output (wastes tokens, dilutes attention)
print("I am thinking about how to solve this problem...")
print("Let me analyze the situation...")
print("I apologize, I made an assumption and was incorrect, let me try again.")

# GOOD: Silent protocol - only structured output
import json
import sys

def agent_output(intent: dict = None, error: str = None, result: dict = None):
    """
    The Silent Output Protocol:
    1. Intent (JSON) - what the agent plans to do
    2. Error (stderr) - only actual errors
    3. Result (structured data) - final output
    """
    if intent:
        print(json.dumps({"intent": intent}))

    if error:
        print(error, file=sys.stderr)

    if result:
        print(json.dumps({"result": result}))

# Example usage:
agent_output(intent={"action": "read_file", "path": "/src/main.py"})
# ... execute ...
agent_output(result={"status": "success", "lines": 150})

# If something fails, don't apologize - just try the next approach
# Every token spent on politeness is a token not spent on solving
```

--------------------------------

### Implement API Handler

Source: https://context7.com/kodareken/rethinking-ai/llms.txt

Derive from ApiHandler to process requests. Use RepairableException for errors that the LLM can potentially resolve.

```python
from helpers.api import ApiHandler, Request, Response
from helpers.messages import mq
from agent import AgentContext

class MyHandler(ApiHandler):
    """API handlers derive from ApiHandler in helpers/api.py"""

    async def process(self, input: dict, request: Request) -> dict | Response:
        # Access agent context
        context: AgentContext = request.context

        # Log proactive UI messages
        mq.log_user_message(
            context.id,
            "Processing your request...",
            source="MyHandler"
        )

        try:
            # Business logic here
            result = await self.do_work(input)
            return {"ok": True, "data": result}
        except Exception as e:
            # Use RepairableException for errors LLM might fix
            from helpers.exception import RepairableException
            raise RepairableException(f"Failed: {e}")
```

--------------------------------

### Define Backend API Handler

Source: https://github.com/kodareken/rethinking-ai/blob/main/Agent Zero - AGENTS.md

Derive from ApiHandler in helpers/api.py to process requests.

```python
from helpers.api import ApiHandler, Request, Response

class MyHandler(ApiHandler):
    async def process(self, input: dict, request: Request) -> dict | Response:
        # Business logic here
        return {"ok": True, "data": "result"}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.