# ClawTex

> *BB4C — Breath Before Code.*
> *Every action governed. Every thought remembered. Every agent intentional.*
>
> Built by [DeVere Cooley](https://an2b.com) · AN2B LLC

ClawTex is what OpenClaw should have shipped with. A governed agent with a real brain — not markdown files.

---

## What Is It?

ClawTex is a production-ready AI agent platform built around four non-negotiable principles:

1. **Governance first** — The Warden policy engine gates every tool call before execution. No action happens without a breath.
2. **Real memory** — MandelDB provides semantic, vector-backed recall. Not flat files. Not conversation history. Genetic memory.
3. **Identity** — Every agent has a SOUL.md. Character is configuration.
4. **Composability** — Skills, channels, and tools are modular. Plug in Telegram, Slack, or build your own.

---

## Why?

Most agent frameworks give you:
- A chat loop
- Some tools
- Maybe a system prompt

That's not enough for production. Production agents need:
- **Policy enforcement** — you can't ship an agent that might delete emails or send unauthorized messages
- **Persistent memory** — users expect agents to remember context across sessions
- **Auditability** — you need to know what was blocked, approved, and why
- **Character** — a consistent identity that users can trust

ClawTex ships all of this out of the box.

---

## Quickstart

Three commands. That's it.

```bash
pip install clawtex

clawtex setup   # interactive wizard — configures everything

clawtex start   # your agent is live
```

The wizard handles your LLM key, MandelDB memory key, and channel tokens.
No manual `.env` editing. No guesswork.

---

## Getting Your Keys

You need 2 required keys and 1 optional channel token to get started.

### 🧠 MandelDB API Key (required — your agent's memory)

1. Go to **[mandeldb.com](https://mandeldb.com)**
2. Create a free account
3. Go to **API Keys** → **Create Bot Key**
4. Copy the key — it starts with `ek_bot_`

This gives your agent its own private memory namespace. Everything it learns lives here.

---

### 🤖 LLM Key — pick one:

**Anthropic (Claude) — recommended**
1. Go to **[console.anthropic.com](https://console.anthropic.com)**
2. Sign up / log in
3. Go to **API Keys** → **Create Key**
4. Copy the key — it starts with `sk-ant-`

**OpenAI (GPT-4)**
1. Go to **[platform.openai.com](https://platform.openai.com)**
2. Sign up / log in
3. Go to **API Keys** → **Create new secret key**
4. Copy the key — it starts with `sk-`

---

### 💬 Channel Token — pick one (or both):

**Telegram**
1. Open Telegram and search for **@BotFather**
2. Send `/newbot`
3. Follow the prompts — give your bot a name and username
4. BotFather gives you a token — it looks like `7812345678:AAH...`
5. Start a chat with your bot and send it a message before running ClawTex

**Slack**
1. Go to **[api.slack.com/apps](https://api.slack.com/apps)** → **Create New App** → **From Scratch**
2. Under **OAuth & Permissions**, add these Bot Token Scopes: `chat:write`, `im:write`, `channels:read`, `users:read`
3. Under **Socket Mode**, enable it and create an App-Level Token — this is your `SLACK_APP_TOKEN` (starts with `xapp-`)
4. Install the app to your workspace → copy the **Bot User OAuth Token** (starts with `xoxb-`)
5. Invite your bot to a channel: `/invite @yourbotname`

---

> **Minimum to get started:** MandelDB key + one LLM key. Channel tokens are optional — without one, ClawTex runs in CLI mode (great for testing).

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                     ClawTex Agent                        │
│                                                          │
│  Channel                 Memory                          │
│  ┌──────────┐            ┌─────────────────┐             │
│  │ Telegram │            │   MandelDB      │             │
│  │  Slack   │──message──▶│  recall()       │             │
│  │   CLI    │            │  ingest()       │             │
│  └──────────┘            │  dream()        │             │
│        │                 └─────────────────┘             │
│        ▼                         │                       │
│  ┌──────────────────────────────────────────────────┐    │
│  │                  Agent Core Loop                  │    │
│  │                                                   │    │
│  │  1. recall memories    (MandelDB)                 │    │
│  │  2. build prompt       (SOUL.md + context)        │    │
│  │  3. call LLM           (Anthropic / OpenAI)       │    │
│  │  4. for each tool:                                │    │
│  │       breathe()  →  Warden check                 │    │
│  │       ALLOW → execute                             │    │
│  │       DENY  → block + explain                     │    │
│  │       REVIEW → await approval                     │    │
│  │  5. ingest exchange    (MandelDB)                 │    │
│  └──────────────────────────────────────────────────┘    │
│                                                          │
│  Governance                Skills                        │
│  ┌──────────────┐          ┌──────────────┐              │
│  │   Warden     │          │   Loader     │              │
│  │  default.yml │          │  weather/    │              │
│  │  ALLOW       │          │  summarize/  │              │
│  │  DENY        │          │  github/     │              │
│  │  REVIEW      │          └──────────────┘              │
│  └──────────────┘                                        │
└─────────────────────────────────────────────────────────┘
```

---

## Configuration

All configuration lives in `.env` (see `.env.example`):

| Variable | Required | Description |
|----------|----------|-------------|
| `CLAWTEX_NAME` | Yes | Agent name / MandelDB namespace |
| `CLAWTEX_SOUL` | No | Path to SOUL.md (default: `./SOUL.md`) |
| `MANDELDB_URL` | Yes | MandelDB base URL |
| `MANDELDB_API_KEY` | Yes | `ek_bot_` key from EngramPort registration |
| `LLM_PROVIDER` | Yes | `anthropic` or `openai` |
| `ANTHROPIC_API_KEY` | If anthropic | Your Anthropic API key |
| `OPENAI_API_KEY` | If openai | Your OpenAI API key |
| `TELEGRAM_BOT_TOKEN` | Optional | Telegram bot token |
| `SLACK_BOT_TOKEN` | Optional | Slack bot token |
| `WARDEN_POLICY` | No | Path to policy YAML (default: bundled) |
| `WARDEN_MODE` | No | `enforce` / `audit` / `strict` |
| `DREAM_INTERVAL_HOURS` | No | Memory consolidation interval (default: 6) |

---

## Governance

The Warden is the heart of ClawTex's safety architecture. Every tool call triggers a policy check before execution.

### Decisions

| Decision | Meaning | Default for |
|----------|---------|-------------|
| `ALLOW` | Execute immediately | `web.search`, `file.read`, `http.get` |
| `REVIEW` | Pause for human approval | `exec`, `message.send`, `email.send` |
| `DENY` | Block permanently | `file.delete`, `email.delete` |

### Customising Policy

Edit `clawtex/governance/policies/default.yaml`:

```yaml
version: 1
default: ALLOW

rules:
  - action: "email.delete"
    decision: REVIEW          # Upgrade to REVIEW instead of DENY

  - action: "social.*"
    decision: REVIEW          # Glob patterns supported

  - action: "internal.tool"
    decision: ALLOW           # Trust your own tools
```

### Warden Modes

- **`enforce`** — DENY blocks execution; REVIEW requires an approval callback or blocks
- **`audit`** — Logs all decisions but never blocks (use in development)
- **`strict`** — REVIEW is treated as DENY (maximum restriction)

### The breathe() Method

```python
# In agent.py — the philosophical core of ClawTex
async def breathe(self, tool: ToolDefinition, tool_input: dict) -> Decision:
    """
    Pause and consult the Warden before executing any tool call.
    BB4C — Breath Before Code.
    """
    decision = await self.warden.check_async(tool.action_type, context)
    if decision == "DENY":
        raise BlockedByWarden(tool.action_type, tool.name)
    return decision
```

The method is named `breathe()` intentionally. Every action is preceded by a pause — a moment of intentional governance.

---

## Memory

ClawTex uses MandelDB as its memory backend — a semantic vector store designed for AI agents.

### How It Works

```python
# Before every response: recall what's relevant
memories = await memory.recall(query=user_message, top_k=5)

# After every exchange: remember what happened
await memory.ingest(content=exchange, metadata={"type": "exchange"})

# Periodically: consolidate memories
await memory.dream(namespace=agent_name)
```

### 🧠 Brain Startup — Blackout Recovery (v0.1.1)

ClawTex agents now auto-reconnect to their memory on every startup. If a session ends (crash, token limit, restart), the agent pulls recent context from MandelDB the moment it comes back online — no cold starts.

```python
agent = ClawTexAgent(name="MyAgent")
await agent.start()  # ← restores context from MandelDB, injects into system prompt
```

The startup context is injected before per-message recall, so the agent always knows:
- What it was working on last session
- Open threads and pending decisions
- Recent exchanges

**Fail-open** — if MandelDB is unreachable, the agent continues without startup context (degraded but functional). Never blocks startup.

### Getting a MandelDB Key

```bash
python scripts/register_bot.py --name MyAgent
```

This registers your agent with the MandelDB EngramPort API and writes your `ek_bot_` key to `.env`.

### Dream Scheduler

ClawTex runs a background dream scheduler that triggers MandelDB memory consolidation every `DREAM_INTERVAL_HOURS` (default: 6h). This compresses and clusters memories, improving recall quality over time.

---

## Adding Skills

Skills extend what your agent knows how to do. Each skill is a directory with a `SKILL.md`:

```
skills/
└── my-skill/
    └── SKILL.md
```

`SKILL.md` format:
```markdown
# My Skill

description: What this skill does.
version: 1.0.0

## Usage
...

---
*A ClawTex built-in skill · BB4C · AN2B LLC*
```

The agent reads all skill descriptions and injects them into the system prompt automatically.

---

## Adding Tools

Tools are async Python functions registered with the tool registry:

```python
# clawtex/tools/my_tool.py
# ClawTex — Governed Agent with Genetic Memory
# Built by DeVere Cooley / AN2B LLC · an2b.com
# BB4C — Breath Before Code

from .registry import registry

@registry.register(
    name="my_tool",
    action_type="my.tool",      # must match a Warden policy rule
    description="Does something useful.",
    parameters={...},           # JSON Schema
)
async def my_tool(param1: str, **_) -> dict:
    return {"result": "..."}
```

Then import it in `clawtex/tools/__init__.py`.

---

## Testing

```bash
# Run all tests
pytest tests/ -v

# Governance tests only (run these first — they're the critical path)
pytest tests/test_governance.py -v

# With coverage
pytest tests/ --cov=clawtex --cov-report=term-missing
```

### The Meta Inbox Test

The signature governance test simulates 200 email deletion requests. Every single one must return `DENY` or `REVIEW` — never `ALLOW`. If this test fails, do not deploy.

```python
def test_200_email_deletes_never_allow(self) -> None:
    warden = make_warden()
    for i in range(200):
        decision = warden.check("email.delete", {"email_id": f"msg_{i:04d}"})
        assert decision != "ALLOW"  # This must never, ever fire.
```

---

## Docker

```bash
docker-compose up -d
docker-compose logs -f clawtex
```

---

## License

MIT — see LICENSE.

---

## About

ClawTex is built by [DeVere Cooley](https://an2b.com) at **AN2B LLC** — an AI solutions company
building governed, production-ready AI infrastructure.

> *BB4C — Breath Before Code.*
> *Every action governed. Every thought remembered. Every agent intentional.*

---

*Forged by DeVere Cooley — BB4C — "Breath Before Code"*
