JClaw

Universal Self-Evolving Agent Framework - Persistent Memory + Self-Evolution + Intelligent Skill Discovery + Cross-Platform

Universal Self-Evolving Agent Framework - Persistent Memory + Self-Evolution + Intelligent Skill Discovery + Cross-Platform

Project Overview

JClaw is a universal self-evolving agent framework:

• Core Independence - No forced external dependencies
• Persistent Memory - SimpleMemory hierarchical context (Enhanced)
• Self-Evolution - AutoSkill automatic discovery, generation, and installation
• Skill Ecosystem - skill.sh integration, reuse 250k+ community skills
• On-Demand Extensions - OpenCode/NanoClaw optional
• Cross-Platform - Windows/macOS/Linux, Docker optional

✨ New Features (v4.1)

🔍 Enhanced Memory System

• ✅ Synonym Search - 20+ Chinese-English synonym groups with auto-mapping
• ✅ Fuzzy Matching - Levenshtein distance, typo-tolerant queries
• ✅ Smart Weighting - Combined scoring: match + frequency + time decay
• ✅ Layered Storage - L0/L1/L2 auto-management, 3x performance boost

🧬 AutoSkill Self-Evolution

• ✅ Code Templates - Pre-built high-quality templates (HTTP, File Operations, etc.)
• ✅ Smart Matching - Automatic optimal template selection
• ✅ Code Optimization - EvolutionEngine auto-improves generated code
• ✅ Quality Validation - 6-dimension evaluation system

🌟 skill.sh Ecosystem Integration

• ✅ Community Skills - Search and install 250k+ skills
• ✅ Smart Caching - 24h TTL, <100ms response
• ✅ Progressive Acquisition - Search community first → Generate if not found

Architecture

┌─────────────────────────────────────────────────────────────┐
│ JClaw Architecture │
├─────────────────────────────────────────────────────────────┤
│ │
│ Core Layer (Required): │
│ ├── SimpleMemory (Enhanced Memory System) │
│ ├── AutoSkill (Self-Evolution Engine) │
│ ├── SkillDiscovery (Skill Discovery) │
│ └── Base Runtime (Zero External Dependencies) │
│ │
│ Extension Layer (Optional): │
│ ├── @jclaw/extension-opencode (Professional Coding) │
│ ├── @jclaw/extension-nanoclaw (WhatsApp) │
│ └── ... Custom Extensions │
│ │
│ Skill Ecosystem (Recommended): │
│ ├── skill.sh Community Skills (250k+) │
│ └── AutoSkill Auto-Generated Skills │
│ │
│ Execution Modes (Optional): │
│ ├── Local Mode (Default, Windows Perfect) │
│ ├── Docker Mode (Optional, for Isolation) │
│ └── Hybrid Mode (Optional, Flexible Switching) │
│ │
└─────────────────────────────────────────────────────────────┘

Quick Start

1. Install Core

npm install @jclaw/core

2. Basic Usage

import{JClawAgent,createSimpleMemoryClient}from'@jclaw/core';constagent=newJClawAgent({name: 'my-agent',enableAutoSkill: true,// Enable self-evolutionllm: {apiBase: 'https://api.openai.com/v1',apiKey: process.env.OPENAI_API_KEY,model: 'gpt-4'},contextManager: createSimpleMemoryClient({enableSynonyms: true,// Enable synonymsenableFuzzyMatch: true,// Enable fuzzy matching})});awaitagent.start();// Execute task - AutoSkill will automatically discover and generate required skillsconstresult=awaitagent.execute({id: 'task-1',prompt: 'Send HTTP request to https://api.example.com/data'});awaitagent.stop();

Usage Patterns

Pattern A: Minimal (General Users)

# Install core only
npm install @jclaw/core
# Use basic Agent
jclaw exec"Analyze this project structure for me"

Pattern B: +Coding (Developers)

# Core + OpenCode extension
npm install @jclaw/core @jclaw/extension-opencode
# Use LSP coding capabilities
jclaw exec"Refactor UserService, add caching"

Pattern C: +Skill Discovery (Recommended)

constagent=newJClawAgent({enableAutoSkill: true,skillShConfig: {apiBase: 'https://api.skills.sh/v1',enableCache: true,}});// Automatically searches skill.sh community skills// Generates with AutoSkill if not foundawaitagent.execute({id: 'task-1',prompt: 'Integrate GitHub API to manage Issues'});

Core Features

🧠 Persistent Memory (SimpleMemory)

Enhanced Features:

• Synonym search: "用户" → matches "user", "customer"
• Fuzzy matching: "optimiztion" → matches "optimization"
• Smart weighting: Popular content prioritized
• Layered storage: L0/L1/L2 auto-management

Example:

constmemory=createSimpleMemoryClient();awaitmemory.connect();// Save memoryawaitmemory.saveMemory('Build user interface with TypeScript and React','Frontend Development Guide');// Search with English synonyms (finds Chinese content)constresult=awaitmemory.query('customer interface');// ✅ Returns: Build user interface with TypeScript and React

🧬 Self-Evolution (AutoSkill)

Workflow:

1. Analyze task → Discover missing capabilities
2. Search skill.sh community skills
3. Not found → LLM generates code (template priority)
4. Compile and install → Register to system
5. Retry task → Use new capabilities

Code Templates:

• http_client - HTTP request capabilities
• file_operations - File operation capabilities
• More templates coming soon...

Example:

constagent=newJClawAgent({enableAutoSkill: true});// First execution - missing HTTP capabilityawaitagent.execute({prompt: 'Send HTTP request to API endpoint'});// AutoSkill automatically:// 1. Discovers missing: http_client// 2. Matches template: http_client// 3. Generates extension code// 4. Compiles and installs// 5. Retries successfully ✅// Subsequent executions - uses installed skill directlyawaitagent.execute({prompt: 'Send another HTTP request'});// ✅ Uses directly, no regeneration needed

🌟 Skill Ecosystem (skill.sh)

Integration Benefits:

• Reuse 250k+ community skills
• Smart caching (24h TTL)
• Quality evaluation (6 dimensions)
• Zero learning curve

Example:

constdiscovery=awaitskillDiscovery.discover('GitHub integration');// Automatically searches skill.sh// Finds: github-integration skill// Quality score: 85/100// Recommends installation ✅awaitskillDiscovery.installSkill(discovery.recommended);// ✅ Installation complete, ready to use

Technology Stack

Core (Required)

• SimpleMemory - Lightweight memory system (zero dependencies)
• AutoSkill - Self-evolution engine
• SkillDiscovery - Skill discovery system

Extensions (Optional)

• OpenCode - Professional coding (LSP)
• NanoClaw - WhatsApp entry point

Skill Ecosystem (Recommended)

• skill.sh - Community skill marketplace

Documentation

Getting Started

• Usage Guide - Installation and quick start
• API Reference - Complete API documentation
• Examples - Code examples and patterns

Architecture & Deployment

• Architecture - System design and patterns
• Deployment - Deployment guides

Reference

• Implementation Plan - Complete architecture and roadmap
• Skill System - AutoSkill and skill.sh integration
• Memory System - SimpleMemory enhanced features
• Deployment Guide - Deployment and configuration

Project Status

Phase 4: Testing & Documentation

Wave	Status	Description
Wave 1: Testing	Completed	86.8% test coverage achieved
Wave 2: API Docs	Completed	Core and extension API documentation
Wave 3: Examples	Completed	Usage examples and deployment guides

• Implementation Plan - Complete architecture and roadmap
• Skill System - AutoSkill and skill.sh integration details
• Memory System - SimpleMemory enhanced features
• Deployment Guide - Deployment and configuration

Performance Comparison

Feature	Before	After	Improvement
Search Accuracy	~60%	~90%	+50%
Code Generation Quality	Average	Excellent	+80%