TrinityClaw/trinityclaw

TrinityClaw AI Agent

A self-modifying AI agent with persistent memory, dynamic skill creation, and intelligent reasoning capabilities.

## 🖥️ LOCAL USE ONLY TrinityClaw is designed for personal local servers — do not deploy it on a VPS or any public-facing server. The agent API has no rate limiting and no multi-user authentication layer. The code_executor and terminal skills run arbitrary code inside Docker, and the single TRINITY_API_KEY is not sufficient protection for an internet-exposed host. Running this on a public IP without additional firewall rules and a reverse proxy with proper auth could expose your system to unauthorized access. Recommended setup: run on your home machine or a local network server, accessed via your LAN or a private VPN (e.g. Tailscale, WireGuard). Do not open ports 8001, 8080, or 8090 to the public internet.

⚠️ Security Notice

TrinityClaw is secure by design in its original form:

• —All skills run inside an isolated Docker container with no host access
• —Dynamic skill creation uses AST validation and a module ban-list to block dangerous code
• —The agent API is protected by a randomly-generated TRINITY_API_KEY
• —Telegram integration only responds to your specific Chat ID
• —Core skills are read-only inside the container; only skills/dynamic/ is writable by the agent

However, any modification to the codebase can introduce risk. This is an inherent property of self-modifying AI agent systems:

• —Editing core skills, relaxing the module ban-list, or adding new file-system access can expand the attack surface
• —Prompt injection via untrusted web content or external data sources is a known risk class for all LLM agents
• —Credentials in .env (API keys, SMTP passwords, Telegram tokens) should be treated as sensitive — never commit .env to a public repository
• —The code_executor and terminal skills run code inside the container — review any AI-generated code before executing it on sensitive systems
• —Dynamic skills created by the agent should be inspected before being promoted to skills/core/

This project follows responsible AI agent design practices, but no system is unconditionally safe once modified. If you extend or customize TrinityClaw, you take on responsibility for auditing those changes.

Features

• —Self-Modifying: Creates new skills dynamically
• —Persistent Memory: ChromaDB vector storage + JSONL logs, daily journaling, goal tracking, and weekly meta-review synthesis across all memory files
• —Multi-Step Reasoning: Agent loop for complex tasks
• —Dynamic Skills: Core system skills + user-created skills
• —Web Browsing: Fetch and analyze web content, including JS-rendered pages
• —Browser Automation: Full Playwright-powered browser control — navigate, click, type, screenshot, evaluate JS, fill forms
• —Live Browser Session: Attach to your existing logged-in Chrome via CDP — post to Twitter/X, LinkedIn, Instagram, and any platform directly from the agent using your real sessions, no API keys required
• —Scheduler: Run automated tasks
• —Telegram Integration: Chat with your agent via text, voice messages, and photos
• —Google Calendar: Read, create, update, and delete calendar events — just ask naturally
• —Gmail Integration: Read inbox, search emails, download attachments, mark as read — full Gmail API access
• —Business Knowledge Base: Drop your documents into a folder and the agent learns from them — meeting notes, SOPs, contracts, spreadsheets
• —Voice Messages: Send audio to Telegram or web UI — transcribed locally via Whisper (no API key needed)
• —Image Vision & OCR: Send photos via Telegram or web UI — described by a vision-capable LLM; local OCR (Tesseract) extracts text from screenshots, documents, and receipts in English, Italian, Spanish, French, Greek, and Serbian (Cyrillic + Latin)
• —Secure: AST validation, skill whitelisting, Docker isolation

Quick Start

Prerequisites

• —Docker Desktop (the only prerequisite — it's free): https://www.docker.com/products/docker-desktop/
• —Windows: Docker Desktop requires WSL 2. On Windows 11, WSL is already built in — Docker Desktop's installer enables it automatically. No manual WSL setup needed.
• —Mac: Download the .dmg, drag Docker to Applications, open it, and wait for the whale 🐳 icon in your menu bar.
• —8GB+ RAM recommended
• —20GB free disk space (50GB+ for local model)

No Git required on Windows or Mac. The installers download the repository automatically. Browser automation (Playwright + Chromium, ~300MB) is installed automatically inside the Docker container during build — no extra steps required.

Install — Windows

Step 1 — Install Docker Desktop

1. 1.Go to https://www.docker.com/products/docker-desktop/
2. 2.Click Download for Windows
3. 3.Run the installer (it enables WSL 2 automatically on Windows 11)
4. 4.Open Docker Desktop from the Start menu
5. 5.Wait for the whale 🐳 icon to appear in your taskbar — Docker is ready when you see it

Step 2 — Run the installer

Press Win + R, paste the command below, and hit Enter:

powershell -Command "irm https://raw.githubusercontent.com/TrinityClaw/trinity-claw/main/install.ps1 | iex"

No admin required. No Git required. No file to download.

A terminal window opens and walks you through setup automatically:

• —If Docker isn't running yet, the installer starts it and waits
• —If Docker isn't installed, it opens the download page for you
• —Downloads the full TrinityClaw repo automatically
• —Launches the installer wizard — choose cloud or local model

At the end, your Agent API Key is printed — copy it and paste it in the Web UI under Settings ⚙️ → Agent Security.

After install, TrinityClaw starts automatically every time Windows boots. A "Start TrinityClaw" shortcut is placed on your Desktop for manual restarts.

Install — macOS

Step 1 — Install Docker Desktop

1. 1.Go to https://www.docker.com/products/docker-desktop/
2. 2.Click Download for Mac
3. 3.Open the .dmg file → drag Docker to Applications
4. 4.Open Docker Desktop from Applications
5. 5.Wait for the whale 🐳 icon in your menu bar — Docker is ready when you see it

Step 2 — Run the installer

Open Terminal (press ⌘ Space, type Terminal, press Enter) and paste:

curl -fsSL https://raw.githubusercontent.com/TrinityClaw/trinity-claw/main/install.sh | bash

The installer will:

• —Start Docker Desktop automatically if it's installed but not running
• —Install docker-compose via Homebrew if needed (for local model mode)
• —Download the repo if you're running via curl
• —Walk you through choosing cloud or local model
• —Set up a LaunchAgent so TrinityClaw starts automatically on every login
• —Place a "Start TrinityClaw.command" shortcut on your Desktop

At the end, copy your Agent API Key and enter it in the Web UI under Settings ⚙️ → Agent Security.

Already have the repo cloned? cd into it and run bash install.sh instead.

Install — Linux

curl -fsSL https://raw.githubusercontent.com/TrinityClaw/trinity-claw/main/install.sh | bash

Docker Engine is installed automatically if not present. That's it.

During installation you will be asked to choose:

• —Cloud — use a remote provider (OpenAI, NVIDIA, Anthropic, etc.) — requires API key
• —Local — use Ollama with qwen3.5:9b running on your machine — no API key needed (~6.6 GB download)

After installation, open the Web UI at: http://localhost:8080

Configuration

LLM Setup

Choose your model source during installation:

Option A — Cloud Provider (requires API key)

Option B — Local Model via Ollama (no API key needed)

• —Model: qwen3.5:9b (~6.6GB download on first start)
• —Requires: 8GB+ VRAM (GPU) or 16GB+ RAM (CPU-only, slower)
• —On Linux: pulled automatically by ollama-entrypoint.sh inside Docker on first startup
• —On Mac: pulled during install.sh via native Ollama (Homebrew)
• —Start command: docker compose --profile local up -d (Linux) / docker compose -f docker-compose.mac.yml up -d (Mac)
• —Mac auto-start: after running install.sh, TrinityClaw starts automatically on every login — no terminal needed. A Start TrinityClaw.command shortcut is placed on your Desktop as a manual backup.

# Linux — start with local Ollama model
docker compose --profile local up -d

# Monitor model download progress (Linux)
docker logs trinity-claw-ollama-1 -f

# If the model was not pulled automatically, pull it manually:

# Mac (native Ollama)
ollama pull qwen3.5:9b

# Linux (inside Docker container)
docker exec trinity-claw-ollama-1 ollama pull qwen3.5:9b

Supported Providers

Configuration Files

trinity-claw/
├── .env                        # Secrets (API keys)
├── identity.md                 # Agent personality, values, and standing orders (editable)
└── config/
    └── litellm_config.yaml     # Model configuration

identity.md defines who TrinityClaw is — its values, communication style, and standing orders. Edit this file to customize the agent's personality without touching any Python code. Changes take effect on the next chat request (no restart needed).

.env example:

NVIDIA_API_KEY=nvapi-xxxxx
LITELLM_MASTER_KEY=sk-trinity-local-key
TRINITY_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # auto-generated by installer
TAVILY_API_KEY=tvly-xxxxx                            # optional — get free key at tavily.com

litellm_config.yaml example:

model_list:
  - model_name: trinity-default
    litellm_params:
      model: openai/moonshotai/kimi-k2-instruct
      api_key: os.environ/NVIDIA_API_KEY
      api_base: https://integrate.api.nvidia.com/v1

  # Vision model — used automatically when photos are sent.
  # If your main model supports vision (gpt-4o, claude-3-5-sonnet) set both to the same model.
  # For NVIDIA text-only models, use a dedicated vision model:
  - model_name: trinity-vision
    litellm_params:
      model: openai/meta/llama-3.2-90b-vision-instruct
      api_key: os.environ/NVIDIA_API_KEY
      api_base: https://integrate.api.nvidia.com/v1

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Agent Security (API Key)

During installation, a random `TRINITY_API_KEY` is automatically generated and written to .env. It is printed at the end of the installer — copy it and enter it once in the Web UI.

How it works:

What it protects:

• —POST /config/update — changing your LLM model/provider
• —POST /config/update-api-key — writing API keys to .env
• —POST /config/telegram/update — Telegram bot credentials
• —POST /config/model-source/set — switching local/cloud

Note: If TRINITY_API_KEY is not set in .env, the check is silently skipped (backward compatible). Read-only endpoints like /health, /skills, /chat are not protected by this key.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    TRINITYCLAW ARCHITECTURE                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────────────────────────────────────────────┐  │
│   │                    app.py                            │  │
│   │         (Nervous System - Coordination)              │  │
│   │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │  │
│   │  │Chat API  │ │  Skills  │ │  Memory  │            │  │
│   │  │          │ │ Registry │ │ Manager  │            │  │
│   │  └──────────┘ └────┬─────┘ └──────────┘            │  │
│   └────────────────────┼────────────────────────────────┘  │
│                        │                                   │
│              ┌─────────┴─────────┐                        │
│              ▼                   ▼                        │
│   ┌─────────────────┐  ┌─────────────────┐               │
│   │  skills/core/   │  │ skills/dynamic/ │               │
│   │  (Read-only)    │  │  (Read-write)   │               │
│   │  - notes        │  │  - (AI creates) │               │
│   │  - files        │  │                 │               │
│   │  - web          │  │                 │               │
│   │  - code_executor│  │                 │               │
│   │  - create_skill │  │                 │               │
│   │  - git_manager  │  │                 │               │
│   │  - scheduler    │  │                 │               │
│   │  - telegram_bot │  │                 │               │
│   │  - meta_review  │  │                 │               │
│   └─────────────────┘  └─────────────────┘               │
│                                                             │
│   ┌─────────────────────────────────────────────────────┐  │
│   │    LiteLLM ◄────────► External LLM Provider         │  │
│   └─────────────────────────────────────────────────────┘  │
│                                                             │
│   ┌─────────────────────────────────────────────────────┐  │
│   │    ChromaDB + JSONL ◄─── Persistent Memory          │  │
│   └─────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Core Skills (31)

Live Browser Session

The browser_session dynamic skill lets the agent attach to your existing logged-in Chrome via Chrome DevTools Protocol (CDP). Unlike the web skill which launches a fresh private browser with no sessions, browser_session sees everything you're logged into — Twitter/X, LinkedIn, Instagram, WordPress, and any other platform — and can interact with it exactly like a human would.

One-Time Setup

1. Create a Chrome shortcut. Right-click Desktop → New → Shortcut → paste this as the target, name it ChromeTrinity:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\ChromeDebug"

--user-data-dir is required — it forces Chrome to start as a fully independent process. Without it, Chrome hands off to any existing instance and the debug flag is ignored.

Before launching: close all Chrome windows and kill any chrome.exe in Task Manager → Details tab.

2. Create the port proxy — run this once in CMD as Administrator (survives reboots):

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=9223 connectaddress=127.0.0.1 connectport=9222

Chrome on Windows only binds its debug port to 127.0.0.1 (loopback). Docker containers can't reach loopback directly, so this proxy bridges port 9223 on all interfaces to Chrome's port 9222. Verify:

netstat -an | findstr 9223

You should see TCP 0.0.0.0:9223 LISTENING. This rule persists across reboots — you only need to run it once.

3. Launch ChromeTrinity and verify Chrome is listening:

netstat -an | findstr 9222

You should see TCP 127.0.0.1:9222 LISTENING.

4. Log in once to Twitter, LinkedIn, Instagram, etc. in this ChromeDebug profile. Sessions are saved in C:\ChromeDebug and persist forever.

Your normal Chrome and ChromeTrinity run simultaneously with no conflicts.

Linux users: The portproxy is Windows-only. On Linux, launch Chrome with --remote-debugging-address=0.0.0.0 (Linux Chrome honours this flag) and set BROWSER_CDP_URL=http://172.17.0.1:9222 in .env.

Available Functions

Example — Posting a Tweet

browser_session.screenshot()
browser_session.goto("https://x.com")
browser_session.click('[data-testid="SideNav_NewTweet_Button"]')
browser_session.type_text('[data-testid="tweetTextarea_0"]', "Your content here")
browser_session.screenshot()   ← verify before posting
browser_session.click('[data-testid="tweetButtonInline"]')

What This Replaces

Instead of building separate Twitter API, LinkedIn API, and Instagram API integrations — each requiring OAuth app approval, developer accounts, and rate limits — the agent uses your real browser session on every platform simultaneously. Any site you can use in a browser, the agent can use too.

Skill Invocation

TrinityClaw uses XML-style skill tags:

<skill:skillname.function>arg1,arg2</skill:skillname.function>

Examples

# List files
<skill:files.ls>/app/memory</skill:files.ls>

# Save a note
<skill:notes.save>MyNote,This is important information</skill:notes.save>

# Read a note
<skill:notes.load>MyNote</skill:notes.load>

# Create a skill
<skill:create_skill.create_new_skill>greeter,def greet(name): return f"Hello {name}!"</skill:create_skill.create_new_skill>

# Quick math (no subprocess)
<skill:code_executor.calc>sqrt(144) + 2**8</skill:code_executor.calc>

# Run a Python snippet
<skill:code_executor.run_snippet>print(sum(range(100)))</skill:code_executor.run_snippet>

# Git: check status
<skill:git_manager.status>/app/myrepo</skill:git_manager.status>

# Git: show last 5 commits
<skill:git_manager.log>/app/myrepo,5</skill:git_manager.log>

# Git: stage all and commit
<skill:git_manager.add>/app/myrepo,.</skill:git_manager.add>
<skill:git_manager.commit>/app/myrepo,Fix bug in parser</skill:git_manager.commit>

# Git: pull latest
<skill:git_manager.pull>/app/myrepo</skill:git_manager.pull>

# Fetch webpage (static)
<skill:web.fetch>https://example.com</skill:web.fetch>

# Navigate browser to a JS-rendered page
<skill:web.browser_goto>https://example.com</skill:web.browser_goto>

# Take a screenshot
<skill:web.browser_screenshot>/app/memory/shot.png,true</skill:web.browser_screenshot>

# Extract visible text (after JS execution)
<skill:web.browser_text></skill:web.browser_text>

# Click a button
<skill:web.browser_click>#submit-btn</skill:web.browser_click>

# Type into a search field
<skill:web.browser_type>input[name=q],hello world</skill:web.browser_type>

# Run JavaScript on the page
<skill:web.browser_evaluate>document.title</skill:web.browser_evaluate>

# Close browser when done
<skill:web.browser_close></skill:web.browser_close>

# Schedule a one-time task
<skill:scheduler.schedule>morning_check,tomorrow at 9am,check the news</skill:scheduler.schedule>

# Schedule a recurring task
<skill:scheduler.schedule_recurring>daily_report,24h,summarize today's notes</skill:scheduler.schedule_recurring>

# Create a landing page project
<skill:web_builder.scaffold>my-portfolio,landing</skill:web_builder.scaffold>

# Write/update a file in the project
<skill:web_builder.write_file>my-portfolio,style.css,body { background: #1a1a2e; color: #eee; }</skill:web_builder.write_file>

# Start the live preview server (open http://localhost:8090)
<skill:web_builder.serve>my-portfolio</skill:web_builder.serve>

# Validate index.html structure
<skill:web_builder.validate>my-portfolio</skill:web_builder.validate>

# List all projects
<skill:web_builder.list_projects></skill:web_builder.list_projects>

# Stop the preview server
<skill:web_builder.stop_server></skill:web_builder.stop_server>

# Google Calendar — list next 7 days
<skill:google_calendar.list_events>7</skill:google_calendar.list_events>

# Google Calendar — create an event
<skill:google_calendar.create_event>Team Meeting,2026-03-01,09:00,60,Weekly sync</skill:google_calendar.create_event>

# Google Calendar — find free slots
<skill:google_calendar.find_free_slots>tomorrow,30</skill:google_calendar.find_free_slots>

# Google Calendar — update event title
<skill:google_calendar.update_event>EVENT_ID,title,New Title</skill:google_calendar.update_event>

# Google Calendar — delete an event
<skill:google_calendar.delete_event>EVENT_ID</skill:google_calendar.delete_event>

Creating Custom Skills

Skill Lifecycle

1. 1.Agent creates skill — saved to skills/dynamic/ and immediately usable
2. 2.You inspect the generated file at agent/skills/dynamic/your_skill.py
3. 3.You move it to agent/skills/core/your_skill.py once satisfied (optional — for permanent core status)
4. 4.You tell the agent "activate your_skill" — the agent calls create_skill.reload which reloads all skills from both folders

Skills in dynamic/ are callable right after creation. Moving to core/ just makes them part of the read-only system layer that persists across container rebuilds.

Skill Template

# skills/dynamic/my_skill.py

NAME = "my_skill"
DOC = "Description of what this skill does"

def my_function(arg1: str, arg2: str = "default") -> str:
    """
    Function description.
    
    Args:
        arg1: First argument
        arg2: Second argument (optional)
    
    Returns:
        Result string
    """
    result = f"Processed {arg1} with {arg2}"
    return result

# Add more functions as needed
def another_function():
    return "Another result"

Security Restrictions

Banned modules:

• —shutil, threading, multiprocessing
• —subprocess, socket, ctypes
• —Any module with system-level access

Banned functions:

• —eval(), exec(), compile()
• —fork(), spawn()

Skill Best Practices

1. 1.Return strings - All functions should return str
2. 2.Handle errors - Use try/except blocks
3. 3.Keep it simple - One skill = one purpose
4. 4.Document - Use clear function docstrings
5. 5.Validate input - Check arguments before processing

Telegram Integration

Setup

1. 1.Create Telegram Bot:
2. 2.Open Telegram, search @BotFather
3. 3.Send /newbot, follow instructions
4. 4.Copy the bot token

1. 1.Get Your Chat ID:
2. 2.Search @userinfobot on Telegram
3. 3.Send any message
4. 4.Copy your Chat ID number

1. 1.Configure TrinityClaw:

<skill:telegram_bot.setup>YOUR_BOT_TOKEN,YOUR_CHAT_ID</skill:telegram_bot.setup>
<skill:telegram_bot.start_polling></skill:telegram_bot.start_polling>

1. 1.Test: Message your bot on Telegram!

Supported Message Types

Voice transcription uses faster-whisper running locally inside Docker — no API key required. The model (~150 MB) downloads automatically on the first voice message and is cached in the memory/ volume.

Image vision requires a vision-capable model in trinity-vision (see Configuration above). For local Ollama mode, llama3.2-vision handles images automatically.

Security

• —Only YOUR Chat ID can interact with the bot
• —No open ports required (polling mode)
• —All traffic over HTTPS

Google Calendar Integration

Prerequisites

• —A Google account
• —Docker container running (standard setup — no extra ports needed)

Setup (one-time, ~10 minutes)

Step 1 — Google Cloud Console

1. 1.Go to console.cloud.google.com
2. 2.Create a new project (name it anything, e.g. "TrinityClaw")
3. 3.APIs & Services → Library → search Google Calendar API → Enable
4. 4.APIs & Services → Credentials → + Create Credentials → OAuth client ID
5. 5.If prompted to configure the consent screen:
6. 6.Choose External
7. 7.Fill in an app name → Save
8. 8.Skip Scopes → Save
9. 9.Audience tab → Test users → + Add users → add your Gmail address → Save
10. 10.Back at Create Credentials: select User data, click Next
11. 11.Under credential type choose Desktop app → Create
12. 12.Download JSON → rename the file to gcal_credentials.json

Important: On the "What data will you be accessing?" screen, choose User data (not Application data). Application data creates a service account which won't work for personal calendars.

Step 2 — Copy credentials into the container

# Run from the trinity-claw folder
docker cp gcal_credentials.json trinity-claw-trinity-agent-1:/app/memory/gcal_credentials.json

Step 3 — Authorize (one-time browser step)

Tell your agent:

"Authorize google calendar"

The agent will give you a URL. Open it in your browser, sign in with the same Google account you added as a test user, click Allow, copy the code Google shows you, and paste it back:

"authorize(PASTECODEHERE)"

The token is saved to /app/memory/gcal_token.json and auto-refreshes forever — you never need to do this again.

Usage Examples

Just talk to the agent naturally:

Token Notes

• —The token auto-refreshes as long as refresh_token is present in /app/memory/gcal_token.json
• —If you ever see auth errors after a long time, revoke the app at myaccount.google.com/permissions and re-run authorize()
• —The gcal_credentials.json file stays in /app/memory/ — it survives container rebuilds because /app/memory/ is a Docker volume

Gmail Integration

TrinityClaw supports Gmail in two modes — sending via SMTP (simple, works immediately) and reading via the Gmail API (full inbox access).

Part 1 — Sending Email via Gmail SMTP

This is the quickest way to get email sending working.

Step 1 — Generate a Gmail App Password

Regular Gmail passwords won't work with SMTP. You need an App Password:

1. 1.Make sure 2-Factor Authentication is enabled on your Google account: → https://myaccount.google.com/security

1. 1.Generate an App Password: → https://myaccount.google.com/apppasswords
2. 2.App name: type anything (e.g. TrinityClaw)
3. 3.Click Create
4. 4.Copy the 16-character code Google shows you

Step 2 — Add to .env

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@gmail.com
SMTP_PASSWORD=abcdefghijklmnop

Then restart:

docker-compose restart trinity-agent

Usage Examples

Just tell the agent naturally:

Part 2 — Reading Gmail Inbox (Gmail API)

Full read access to your inbox — list, search, read, download attachments.

Prerequisites

• —Google Cloud project already set up (same one used for Calendar)
• —gcal_credentials.json already in /app/memory/

Step 1 — Enable Gmail API

Go to: https://console.cloud.google.com/apis/library/gmail.googleapis.com

Click Enable (same project as Calendar — no new credentials needed).

Step 2 — Authorize (one-time)

Tell your agent:

"authorize gmail"

The agent will give you a URL. Open it, sign in, click Allow, copy the code, and paste it back:

"authorize gmail with CODE"

Token saved to /app/memory/gmail_token.json — auto-refreshes forever.

Usage Examples

Gmail Search Operators

The agent understands all standard Gmail search operators:

from:john@example.com
subject:invoice
is:unread
has:attachment
after:2026/1/1
from:boss@company.com is:unread has:attachment

Token Notes

• —Token stored at /app/memory/gmail_token.json — separate from Calendar token
• —Auto-refreshes as long as a refresh_token is present
• —If expired: revoke at myaccount.google.com/permissions then call authorize gmail again

Business Knowledge Base

Teach TrinityClaw about your business by dropping documents into a folder. Once ingested, the agent searches your documents automatically before answering business questions — no manual prompting needed.

How It Works

1. 1.Drop files into memory/knowledge/ on your host machine
2. 2.Tell the agent: "ingest my knowledge folder" (or call it directly)
3. 3.Ask questions naturally — the agent searches your docs first

Documents are chunked, embedded, and stored in a dedicated ChromaDB collection (business_knowledge) that is separate from conversation memory.

Supported File Types

PDF, DOCX, DOC, XLSX, XLS, CSV, TXT, MD, JSON, YAML, XML, HTML and more.

Usage Examples

# Index all files in the knowledge folder
<skill:knowledge_base.ingest_folder></skill:knowledge_base.ingest_folder>

# Index a custom folder path
<skill:knowledge_base.ingest_folder>/app/memory/knowledge/</skill:knowledge_base.ingest_folder>

# Ingest a single file
<skill:knowledge_base.ingest_file>meeting-notes-jan.docx</skill:knowledge_base.ingest_file>

# Search your business documents
<skill:knowledge_base.search>refund policy</skill:knowledge_base.search>

# Search with more results
<skill:knowledge_base.search>Q1 sales targets,10</skill:knowledge_base.search>

# List everything that has been indexed
<skill:knowledge_base.list_ingested></skill:knowledge_base.list_ingested>

# Remove a document from the index
<skill:knowledge_base.delete_document>old-contract.pdf</skill:knowledge_base.delete_document>

# Check collection health
<skill:knowledge_base.status></skill:knowledge_base.status>

Re-ingestion & Change Detection

ingest_folder() uses MD5 hash comparison — if a file hasn't changed since the last ingest, it is skipped automatically. Updated files are re-chunked and replaced in ChromaDB. You can safely run ingest_folder() as often as you want.

Automatic Behavior

The agent's identity is configured to:

• —Always search the knowledge base first when asked about meetings, SOPs, clients, policies, or any business-specific topic
• —Proactively remind you to ingest when you mention dropping or uploading files
• —Never say "I don't have that information" for business questions without searching first

Scheduling Automatic Re-ingestion

Use the scheduler skill to keep the knowledge base fresh automatically:

# Re-ingest every morning at 8am
<skill:scheduler.schedule_recurring>kb_sync,24h,ingest my knowledge folder</skill:scheduler.schedule_recurring>

API Reference

Endpoints

Examples

Health check:

curl http://localhost:8001/health

List skills:

curl http://localhost:8001/skills

Chat with agent:

curl -X POST http://localhost:8001/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello TrinityClaw!"}'

Call skill directly:

curl -X POST http://localhost:8001/skill/call \
  -H "Content-Type: application/json" \
  -d '{"skill": "notes", "function": "list", "args": []}'

Persistent Memory System

TrinityClaw builds a growing model of you and your work across every session. Memory is layered:

Daily Journal — notes.end_day()

At 23:00 every night (scheduled automatically) the agent writes a journal entry. You can also trigger it manually:

notes.end_day(
  summary="What was accomplished today",
  next_steps="Pending items or plans for tomorrow",
  user_insights="Patterns observed about your focus areas"
)

The journal is injected into the system prompt at the start of every session (last 3–7 days), so the agent always knows what you worked on recently without you repeating yourself.

Goal Tracking — notes.add_goal() / notes.list_goals()

Track ongoing objectives across sessions:

# Add a goal
notes.add_goal("Launch the new landing page", due_date="2026-05-01")

# List open goals
notes.list_goals()

# Mark done
notes.complete_goal("landing page")

Active goals are automatically injected into the session context so the agent stays oriented toward what matters.

Weekly Meta-Review — meta_review.weekly_digest()

Every Saturday at 08:00 (scheduled automatically) the agent synthesizes all memory files into a single report covering:

• —Top recurring error types and whether fixes exist
• —Lesson fix-coverage rate (how many failures have been addressed)
• —Which autoimprove loops are actually producing improvements (ROI)
• —Recent journal themes and next steps

Run it manually anytime:

meta_review.weekly_digest(7)       ← last 7 days
meta_review.loop_roi_report()      ← per-loop improvement breakdown
meta_review.error_trend_report(30) ← error frequency + fix coverage

Critical findings (unfixed high-frequency errors, low fix coverage) are parked as improvement ideas automatically.

AutoImprove — Overnight Self-Improvement

autoimprove is a dynamic skill that runs autoresearch-style loops while you sleep. It continuously audits your skills, auto-fixes safe issues, queues suggestions for your review, and can research any topic on the web.

How it works

Two-track system:

• —Dynamic skills → auto-fix: snapshot → patch → test → keep or restore
• —Core skills → suggest only: audit → save patch to memory → you approve

Quick start

Tell Trinity:

autoimprove.status()

Put it on autopilot:

autoimprove.schedule_nightly("2am")

Check results in the morning:

autoimprove.report(1)
autoimprove.list_suggestions()

Research — any topic

research() is a general-purpose web research function. Give it any query and it searches the web, fetches the top pages, extracts key content, and saves findings to your notes automatically.

autoimprove.research("Python async best practices")
autoimprove.research("how to improve Playwright reliability", depth="deep")
autoimprove.research("latest trends in local LLM models", depth="deep", save=True)

Parameters: | Parameter | Options | Description | |-----------|---------|-------------| | query | any string | What to research — topic, question, error message, concept | | depth | 'quick' (default) | 1 search + fetches top 2 pages (~15s) | | | 'deep' | 3 search variations + fetches top 5 pages (~45s) | | save | True (default) | Saves findings to notes with a timestamped title |

Results are always saved to memory/notes.json under "Research — [query] — [date]" so they persist across sessions and can be retrieved with notes.search("research").

Improvement loops

Run all loops at once:

autoimprove.run_all(5)       ← max 5 experiments per loop

Run a single loop:

autoimprove.run_loop("ast_audit", 10)
autoimprove.run_loop("suggest_core", 30)

Core skill suggestions

The nightly run scans all core skills and queues proposed fixes. Nothing is applied automatically — you review and approve each one.

# See what's pending
autoimprove.list_suggestions()

# See all (including applied and failed)
autoimprove.list_suggestions("all")

# Apply one approved suggestion to a core skill
autoimprove.apply_suggestion("browser_session", "bare_except")
autoimprove.apply_suggestion("web", "missing_timeout")

Each apply_suggestion() call:

1. 1.Snapshots the core skill file
2. 2.Applies the patch
3. 3.Runs a runtime smoke test
4. 4.Keeps the file if test passes, restores snapshot if it fails

Single experiment

Test one specific fix on a dynamic skill:

autoimprove.run_experiment("seo_analyzer", "bare_except")
autoimprove.run_experiment("content_calendar", "missing_timeout")

View history

autoimprove.report(7)     ← last 7 days
autoimprove.report(1)     ← last 24 hours (useful after a nightly run)
autoimprove.report(30)    ← last month

Memory files

Project Structure

trinity-claw/
├── docker-compose.yml          # Docker orchestration
├── setup.bat                   # Windows installer alternative (double-click, from GitHub Releases)
├── install.ps1                 # Windows installer (run via Win+R one-liner or setup.bat)
├── install.sh                  # Linux/Mac installer
├── .env                        # Secrets (not in git)
├── .env.example                # Secrets template
├── identity.md                 # Agent personality and standing orders (editable)
├── README.md                   # This file
│
├── agent/                      # TrinityClaw agent
│   ├── Dockerfile
│   ├── app.py                  # Main application
│   ├── requirements.txt
│   ├── ollama-entrypoint.sh    # Auto-pulls local model on startup
│   └── skills/
│       ├── __init__.py
│       ├── core/               # System skills (read-only)
│       │   ├── notes.py
│       │   ├── files.py
│       │   ├── web.py
│       │   ├── code_executor.py
│       │   ├── create_skill.py
│       │   ├── git_manager.py
│       │   ├── scheduler.py
│       │   ├── document_parser.py
│       │   ├── data_science.py
│       │   ├── image_viewer.py
│       │   ├── url_monitor.py
│       │   ├── self_improvement.py
│       │   ├── dashboard.py
│       │   ├── terminal.py
│       │   ├── telegram_bot.py
│       │   ├── email_sender.py
│       │   ├── web_builder.py
│       │   ├── google_calendar.py
│       │   ├── knowledge_base.py
│       │   ├── gmail_reader.py
│       │   ├── competitive_intel.py
│       │   ├── google_drive.py
│       │   ├── meeting_notes.py
│       │   ├── youtube.py
│       │   ├── autoimprove.py  # Autoresearch loops + web research (see AutoImprove section)
│       │   ├── meta_review.py  # Weekly synthesis: errors, loop ROI, journal themes
│       │   └── _user_model_store.py  # Internal: user model data layer (used by notes.py)
│       └── dynamic/            # User skills (AI agent can read-write)
│
├── config/
│   └── litellm_config.yaml     # LLM configuration
│
├── memory/                     # Persistent storage (excluded from git except items below)
│   ├── scheduled_tasks1.json   # Starter scheduled task config — rename to scheduled_tasks.json on first run
│   ├── knowledge/              # Drop business documents here for ingestion
│   └── websites/               # web_builder projects (served on port 8090)
│
└── web/
    └── index.html              # Web UI

Maintenance

Basic Commands

# Start services
docker-compose up -d

# Stop services
docker-compose down

# Restart services
docker-compose restart

# View logs
docker logs trinity-claw-trinity-agent-1 --tail 50

# Rebuild after adding core skills
docker-compose down
docker-compose build --no-cache trinity-agent
docker-compose up -d

Backup

# Backup memory
cp -r memory/ backup_$(date +%Y%m%d)/

# Backup everything
tar -czvf trinity_backup_$(date +%Y%m%d).tar.gz memory/ config/ .env

Reset

# Soft reset (keeps memory)
docker-compose down
docker-compose up -d

# Hard reset (deletes everything!)
docker-compose down -v
rm -rf memory/
docker-compose up -d

Troubleshooting

Common Issues

Debug Commands

# Check container status
docker-compose ps

# View agent logs
docker logs trinity-claw-trinity-agent-1 --tail 100

# Check LiteLLM logs
docker logs trinity-claw-litellm-1 --tail 100

# Test API
curl http://localhost:8001/health

# List loaded skills
curl http://localhost:8001/skills

Contributing

1. 1.Fork the repository
2. 2.Create feature branch (git checkout -b feature/amazing-feature)
3. 3.Commit changes (git commit -m 'Add amazing feature')
4. 4.Push to branch (git push origin feature/amazing-feature)
5. 5.Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• —Issues: GitHub Issues
• —Discussions: GitHub Discussions

Version: TrinityClaw v1.4.0 Last Updated: 2026-04-23