clawtex 0.1.2

Governed agent platform with MandelDB genetic memory. BB4C — Breath Before Code.

ClawTex

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

Built by DeVere Cooley · 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.

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
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
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
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 → 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:

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

# 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

# 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.

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

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:

# 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:

# 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

# 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.

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

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

---

License

MIT — see LICENSE.

---

About

ClawTex is built by DeVere Cooley 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"