mochaclaw-js

mochaclaw-js v1.1 (Testing) ☕

Lightweight, local‑first AI agent for Debian
Privacy‑first automation with OpenClaw tactics, powered by Ollama or Transformers.js (WASM).

                    ▖  ▖    ▌     ▜      
                    ▛▖▞▌▛▌▛▘▛▌▀▌▛▘▐ ▀▌▌▌▌
                    ▌▝ ▌▙▌▙▖▌▌█▌▙▖▐▖█▌▚▚▘
                          M O C H A C L A W
              Privacy-first Local AI Agent for Debian

Mochaclaw is a single‑file CLI agent harness that runs entirely on your local machine. It uses Ollama (default) or Transformers.js (WASM) to execute AI workflows without any cloud dependencies. All state (persona, memory, journal) is stored in a single MOCHASOUL.md file – a unified soul that grows with every interaction.

/mochaclaw/
├── mochaclaw           # main executable
├── package.json        # dependencies
├── .env                # optional configuration
├── INSTALL.md          # detailed installation & testing guide
├── MOCHASOUL.md        # auto-created on first run
└── package-lock.json   # will be generated by npm

---

Features

• Dual inference backends:
  • ollama – use any Ollama model (default: qwen2.5:0.5b).
  • transformers – pure WASM execution via Transformers.js (no GPU needed).
• OpenClaw‑style agent loop – Thought → Action → Observation logged in MOCHASOUL.md.
• Built‑in tools – execute shell commands, read/write files, update long‑term memory.
• Interactive & one‑shot modes – chat with the agent or use it in scripts.

Prerequisites

• Node.js v18+ (v22 recommended)
• Ollama (if using the default backend)
• Build tools (only needed for native dependencies if you encounter errors)

  sudo apt update
  sudo apt install build-essential python3 python3-pip -y
  

Custom Model Setup:

Line 18 of the mochaclaw file:

// ----------------------------------------------------------------------
// 1. Configuration
const SOUL_FILE = path.join(process.cwd(), 'MOCHASOUL.md');
const BACKEND = process.env.INFERENCE_BACKEND || 'ollama';
const OLLAMA_URL = process.env.OLLAMA_URL || 'http://localhost:11434';
const OLLAMA_MODEL = process.env.OLLAMA_MODEL || 'qwen2.5:0.5b';

Build

git clone https://github.com/yourusername/mochaclaw.git
cd mochaclaw

Or simply create the files manually in a new directory:

mkdir -p ~/mochaclaw && cd ~/mochaclaw
# ... copy mochaclaw, package.json, .env (optional) from the repository

Install dependencies

npm install

Make the main script executable:

chmod +x mochaclaw

Prepare Ollama

ollama serve          # run in a separate terminal or as a service
ollama pull qwen2.5:0.5b   # or any Ollama model you prefer

Usage

Just run ./mochaclaw. You’ll see the banner and the prompt mocha>.

./mochaclaw

Type your requests normally. The agent will either answer directly or decide to use a tool.
Use the built‑in commands (starting with /) to control the session.

One‑shot mode

Pass your query as an argument. The agent processes it, prints the result, and exits.

./mochaclaw "What files are in my home directory?"

Commands

Tools

The agent can invoke these tools by outputting Action: toolName({ "arg": "value" }).
The tool result is then fed back into the loop (and also logged in the journal).

Configuration (.env)

Create a .env file in the same directory to override defaults:

# Inference backend: "ollama" (default) or "transformers"
INFERENCE_BACKEND=ollama

# Ollama settings (only used if backend = ollama)
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:0.5b (adjust to your own custom model)

# Transformers.js model (only used if backend = transformers)
TRANSFORMERS_MODEL=Xenova/phi-3-mini-4k-instruct

The Soul File: MOCHASOUL.md

This single Markdown file holds the agent’s entire persistent state. It is automatically created on first run with default content, but you can edit it anytime.

# Persona

You are MochaClaw, a privacy-first AI assistant running locally on Debian.
You have access to these tools: run_command, read_file, write_file, update_memory.
When you need to perform an action, output exactly:

Action: toolName({ "arg": "value" })

Then wait for the observation. Otherwise, you may answer directly.

# Memory
- User likes dark mode.
- The home directory contains Documents, Downloads, etc.

# Journal

## Thought
User: What's in my home directory?
I should use run_command to list files.
Action: run_command({ "command": "ls -la ~" })

**Action:** run_command

**Observation:** {"success":true,"output":"total 48\ndrwxr-xr-x ..."}

---

• Persona – the system prompt that defines the agent’s behaviour and tool‑calling format.
• Memory – long‑term facts accumulated via update_memory.
• Journal – chronological log of every Thought → Action → Observation.

Use Cases

-Run MochaClaw offline to scan sensitive directories. Ask it to redact PII from documents using a local NER model (switch to transformers backend with a small BERT model). No data ever leaves your machine.

-Set up a pre‑commit hook that calls MochaClaw to analyse your code diff and generate a journal.md entry documenting your changes. Keep a persistent memory of your project evolution.

-Use the update_memory tool to store facts extracted from your browser history or markdown notes. Later, query your personal knowledge base without ever connecting to the cloud.

-Combine MochaClaw with a simple WebSocket server (not included) to feed hardware metrics (CPU temp, disk usage) into the agent. Ask it to predict failures using a lightweight regression model.

Troubleshooting

Available Tools

run_command

Executes a shell command (with a 5‑second timeout). Arguments: command (string)

read_file

Reads the contents of a file. Arguments: path or file (string)

update_memory

Adds a fact to the long‑term memory section of MOCHASOUL.md. Arguments: content (string)

Example Conversations

Using a tool – list directory contents

text

mocha> Show me what's in my current folder. MochaClaw thinking... Agent: I'll list the files for you. Action: run_command({ "command": "ls -la" }) Observation: {"success":true,"output":"total 48\ndrwxr-xr-x 3 user user 4096 ..."} Answer: The directory contains mochaclaw, package.json, .env, and MOCHASOUL.md.

Read a file

text

mocha> Can you read the file datetime.sh for me? MochaClaw thinking... Action: read_file({ "file": "datetime.sh" }) Observation: {"success":true,"data":"#!/bin/bash\necho "Current date: $(date)"\n"} Answer: Here's the content of datetime.sh: #!/bin/bash echo "Current date: $(date)"

Write a file and then verify

text

mocha> Create a file called test.txt with the text "Hello from MochaClaw". MochaClaw thinking... Action: write_file({ "path": "test.txt", "content": "Hello from MochaClaw" }) Observation: {"success":true} Answer: File test.txt has been created.

mocha> Now read test.txt. MochaClaw thinking... Action: read_file({ "file": "test.txt" }) Observation: {"success":true,"data":"Hello from MochaClaw"} Answer: The file contains: Hello from MochaClaw

Update memory

text

mocha> Remember that I like coffee. MochaClaw thinking... Action: update_memory({ "content": "User likes coffee" }) Observation: {"success":true,"status":"Memory updated"} Answer: I've stored that in my memory.

mocha> /memory Current Memory:

• User likes coffee

License

MIT