Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/imxcstar/sharpclaw

AI agent with long-term memory, built on .NET 10. Supports Anthropic, OpenAI, and Gemini.
https://github.com/imxcstar/sharpclaw

ai ai-agents assistant myclaw nanobot nullclaw openclaw picoclaw zeroclaw

Last synced: 3 months ago
JSON representation

AI agent with long-term memory, built on .NET 10. Supports Anthropic, OpenAI, and Gemini.

Awesome Lists containing this project

README 

          
# 🐾 Sharpclaw



[δΈ­ζ–‡η‰ˆ](README_CN.md)



Sharpclaw is an advanced, highly capable **autonomous AI agent framework** built on **.NET 10**. Its core distinctiveness lies in its robust **cross-conversation long-term memory system** and **system-level operation capabilities**.



By leveraging the `Microsoft.Extensions.AI` abstraction layer, Sharpclaw seamlessly integrates with multiple LLM providers (Anthropic, OpenAI, Gemini) and interacts with users through multiple frontend channels including a Terminal UI (TUI), a Web interface, and QQ Bots.



![Main Chat Window](preview/main.png)



---



## ✨ Key Features



### 🧠 Multi-Tier Long-Term Memory System



* **Three-Layer Pipeline:** Automatically manages context through Working Memory (current session) β†’ Recent Memory (detailed summaries) β†’ Primary Memory (consolidated core facts).

* **Agentic Memory Saver:** An autonomous background agent actively decides what to save, update, or delete after each conversation turn.

* **Vector Database Integration:** Built-in vector search powered by [Sharc](https://github.com/revred/sharc.git) and SQLite, featuring semantic deduplication and a 2-stage retrieval process (Vector Search + DashScope Rerank).



### πŸ› οΈ System Operation Capabilities (Tools/Commands)



* **File System:** Comprehensive file operations including searching, reading, appending, editing, and directory management.

* **Process & Task Management:** Execute native OS commands, external processes, HTTP requests, and manage background tasks. Tasks support foreground (blocking) and background modes, with full lifecycle management including output streaming (stdout/stderr/combined), stdin writing, keyword/regex-based output waiting, and process tree termination. All background tasks are automatically killed and cleaned up on application exit.

* **Sandboxed Python:** Run Python code safely inside a WASM sandbox (see [WASM Python Sandbox](#-wasm-python-sandbox) below).



### 🐍 WASM Python Sandbox



* **Sandboxed Execution:** Runs Python code inside a [RustPython](https://github.com/RustPython/RustPython) WASM module via **Wasmtime** (primary) or **Wasmer** (fallback) runtimes, providing strong hardware-level isolation from the host process.

* **Filesystem Isolation:** File access is strictly limited to `/workspace` (the agent's working directory) and an isolated per-run temporary directory via [WASI](https://wasi.dev/) capability-based security. The host filesystem is completely inaccessible.

* **Guaranteed Timeout:** Wasmtime's **epoch interruption** mechanism enforces a hard, non-bypassable execution timeout (default 180 s), preventing infinite loops and CPU exhaustion.

* **No Shell Injection:** `stdout`/`stderr` are captured at the WASI syscall level via native callbacks, completely bypassing the host shell and eliminating shell-injection risks.

* **Per-Execution Isolation:** Every run creates a fresh WASM engine instance inside a unique GUID-named temporary directory, which is automatically deleted after completion β€” no state leaks between invocations.



### πŸ“± Multi-Channel Support



* **TUI (Terminal.Gui):** A feature-rich terminal interface with collapsible logs, slash-command auto-completion, and configuration dialogs.

* **Web (WebSocket):** A lightweight ASP.NET Core web server with a modern UI (Tokyo Night theme) and real-time streaming.

* **QQ Bot:** Native integration with QQ channels, groups, and private messages.



### πŸ”Œ Extensible Skills System



* **External Skills:** Load custom skills from `~/.sharpclaw/skills/` via `AgentSkillsDotNet`, seamlessly merged with built-in commands as a unified tool collection.



### πŸ”’ Secure Configuration



* Cross-platform secure credential storage (Windows Credential Manager, macOS Keychain, Linux libsecret) using AES-256-GCM encryption for API keys.

* Automatic configuration version migration (up to v8).

* Per-provider custom request body injection (e.g. `"thinking"`, `"reasoning_split"`) β€” configurable globally or per-agent via the Config Dialog.



---



## πŸš€ Getting Started



### Prerequisites



* [.NET 10.0 SDK](https://dotnet.microsoft.com/)

* Git (for cloning submodules)



### Build and Run



1. Clone the repository with its submodules:

```bash

git clone --recursive https://github.com/yourusername/sharpclaw.git

cd sharpclaw

```



2. Build the entire solution:

```bash

dotnet build

```



3. Run the application via the CLI. Sharpclaw routes the startup based on the command provided:



* **Start Terminal UI (Default):**

```bash

dotnet run --project sharpclaw tui

```

First run automatically launches the configuration wizard:



![Config Dialog](preview/config.png)



* **Start Web Server:**

```bash

dotnet run --project sharpclaw web

```



![Web Chat Interface](preview/web.png)



* **Start QQ Bot:**

```bash

dotnet run --project sharpclaw qqbot

```



* **Open Configuration UI:**

```bash

dotnet run --project sharpclaw config

```



---



## πŸ—οΈ Architecture



### System Architecture



```

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

β”‚  Frontend Layer (Channels/)                                  β”‚

β”‚  β”œβ”€β”€ Tui/ β€” Terminal.Gui v2 (ChatWindow, ConfigDialog)      β”‚

β”‚  β”œβ”€β”€ Web/ β€” ASP.NET Core WebSocket server                   β”‚

β”‚  └── QQBot/ β€” QQ Bot integration (Luolan.QQBot)             β”‚

β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€

β”‚  Agent Layer (Agents/)                                       β”‚

β”‚  β”œβ”€β”€ MainAgent β€” Conversation loop, tool orchestration      β”‚

β”‚  β”œβ”€β”€ MemorySaver β€” Autonomous memory management             β”‚

β”‚  └── ConversationArchiver β€” Two-phase memory consolidation  β”‚

β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€

β”‚  Memory Pipeline (Chat/, Memory/)                            β”‚

β”‚  β”œβ”€β”€ MemoryPipelineChatReducer β€” Context window management  β”‚

β”‚  β”œβ”€β”€ VectorMemoryStore β€” Sharc + SQLite vector search       β”‚

β”‚  └── InMemoryMemoryStore β€” Keyword-based fallback           β”‚

β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€

β”‚  Skills & Commands (Commands/, ~/.sharpclaw/skills/)         β”‚

β”‚  β”œβ”€β”€ Built-in β€” File, Process, HTTP, Task, System commands  β”‚

β”‚  β”œβ”€β”€ External Skills β€” AgentSkillsDotNet plugin loading     β”‚

β”‚  └── Memory Tools β€” SearchMemory, GetRecentMemories         β”‚

β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€

β”‚  WASM Python Sandbox (Services/, Interop/, libs/)            β”‚

β”‚  β”œβ”€β”€ WasmtimePythonService β€” RunPython tool (primary)       β”‚

β”‚  β”œβ”€β”€ WasmtimeWasiRuntime β€” Epoch-timeout WASM executor      β”‚

β”‚  β”œβ”€β”€ WasmerWasiRuntime β€” Fallback WASM executor             β”‚

β”‚  └── rustpython.wasm β€” Embedded Python 3 interpreter        β”‚

β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€

β”‚  Core Infrastructure (Core/)                                 β”‚

β”‚  β”œβ”€β”€ AgentBootstrap β€” Shared initialization + skill loading β”‚

β”‚  β”œβ”€β”€ SharpclawConfig β€” Configuration with encryption        β”‚

β”‚  β”œβ”€β”€ ClientFactory β€” LLM client creation                    β”‚

β”‚  β”œβ”€β”€ DataProtector/KeyStore β€” AES-256-GCM encryption        β”‚

β”‚  └── TaskManager β€” Background process management            β”‚

β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

```



### Memory System



Sharpclaw implements a sophisticated three-layer memory pipeline:



| Layer | File | Purpose |

|-------|------|---------|

| **Working Memory** | `working_memory.json` | Current conversation snapshot |

| **Recent Memory** | `recent_memory.md` | Detailed summaries (append-only) |

| **Primary Memory** | `primary_memory.md` | Consolidated core facts |

| **Vector Store** | `memories.db` | Semantic embeddings + metadata |

| **History** | `history/*.md` | Archived full conversations |



**Pipeline Flow:**

1. After each turn β†’ MemorySaver analyzes and updates vector store

2. When context window overflows β†’ Summarizer generates detailed summary β†’ appends to recent memory

3. When recent memory > 30k chars β†’ Consolidator extracts core info β†’ overwrites primary memory



### IChatIO Abstraction



The AI engine is decoupled from frontend through `IChatIO` interface:

- **TUI:** `Channels/Tui/ChatWindow.cs` β€” Terminal.Gui v2 interface

- **Web:** `Channels/Web/WebSocketChatIO.cs` β€” WebSocket frontend

- **QQ Bot:** `Channels/QQBot/QQBotServer.cs` β€” QQ Bot interface



All frontends share the same `MainAgent` logic.



---



## πŸ›‘οΈ WASM Python Sandbox



Sharpclaw provides a fully isolated, secure Python execution environment using **WebAssembly (WASM)** and **WASI** (WebAssembly System Interface). This allows the AI agent to generate and run Python code without any risk to the host system.



### Runtime Stack



| Component | Technology | Role |

|-----------|-----------|------|

| **Python Interpreter** | [RustPython](https://github.com/RustPython/RustPython) compiled to WASM | Python 3 runtime inside sandbox |

| **Primary Runtime** | [Wasmtime](https://wasmtime.dev/) v43 | WASM executor with epoch-based timeout |

| **Fallback Runtime** | [Wasmer](https://wasmer.io/) | Alternative executor |

| **System Interface** | WASI | Capability-based filesystem & I/O abstraction |



### Security Boundaries



| Boundary | Mechanism | Effect |

|----------|-----------|--------|

| **Filesystem** | WASI pre-opened directories | Only `/workspace` and a per-run `/sharpclaw_tmp` are accessible |

| **Memory** | WASM linear memory | Complete isolation from host process memory |

| **Execution Time** | Wasmtime epoch interruption | Hard, non-bypassable timeout (default 180 s) |

| **I/O** | WASI syscall-level callbacks | Output captured before reaching the host shell |

| **Concurrency** | `SemaphoreSlim` mutex | One Python execution at a time, preventing races |

| **State** | Fresh WASM instance per run | No shared state between invocations |



### Execution Flow



```

Agent calls RunPython(code, purpose, timeoutSeconds)

  β”‚

  β–Ό

WasmtimePythonService (acquires mutex)

  β”‚

  β–Ό

WasmtimeWasiRuntime.ExecuteCode()

  β”œβ”€β”€ Create isolated temp dir  (GUID-named, auto-deleted on finish)

  β”œβ”€β”€ Write user code to temp file

  β”œβ”€β”€ Init Wasmtime engine (epoch interruption enabled)

  β”œβ”€β”€ Configure WASI:

  β”‚     β”œβ”€β”€ Pre-open /workspace  (rw)

  β”‚     β”œβ”€β”€ Pre-open /sharpclaw_tmp  (rw)

  β”‚     β”œβ”€β”€ Capture stdout/stderr via native callbacks

  β”‚     └── Set env vars (PWD=/workspace only)

  β”œβ”€β”€ Instantiate rustpython.wasm  +  call _start

  β”œβ”€β”€ Start timeout watchdog (Task.Delay β†’ increment epoch)

  └── Return WasmCommandResult { Success, ExitCode, StdOut, StdErr, TimedOut }

```



### Capability Matrix



| Capability | Status | Notes |

|-----------|--------|-------|

| Standard Python library | βœ… | Frozen into rustpython.wasm |

| File I/O in `/workspace` | βœ… | Maps to the agent's working directory on the host |

| Arbitrary computation | βœ… | No restrictions beyond timeout |

| Host filesystem (outside workspace) | ❌ | Blocked by WASI capability model |

| Native extensions (`.so`/`.dll`) | ❌ | WASM cannot load host shared libraries |

| Spawning host processes | ❌ | No `subprocess`/`os.system` to host |

| Unrestricted network access | ❌ | No WASI socket mapping by default |



---



## πŸ“ Project Structure



```

sharpclaw/

β”œβ”€β”€ sharpclaw/                   ← Main project

β”‚   β”œβ”€β”€ Program.cs               ← Entry point (tui/web/qqbot/config)

β”‚   β”œβ”€β”€ sharpclaw.csproj         ← Project file (net10.0)

β”‚   β”œβ”€β”€ Abstractions/            ← IChatIO, IAppLogger interfaces

β”‚   β”œβ”€β”€ Agents/                  ← MainAgent, MemorySaver, ConversationArchiver

β”‚   β”œβ”€β”€ Channels/                ← Tui, Web, QQBot frontends

β”‚   β”œβ”€β”€ Chat/                    ← MemoryPipelineChatReducer

β”‚   β”œβ”€β”€ Clients/                 ← DashScopeRerankClient, ExtraFieldsPolicy

β”‚   β”œβ”€β”€ Commands/                ← All tool implementations

β”‚   β”œβ”€β”€ Core/                    ← Config, Bootstrap, TaskManager

β”‚   β”œβ”€β”€ Memory/                  ← IMemoryStore, VectorMemoryStore

β”‚   β”œβ”€β”€ UI/                      ← ConfigDialog, AppLogger

β”‚   └── wwwroot/                 ← Web UI (index.html)

β”œβ”€β”€ preview/                     ← Screenshots

β”œβ”€β”€ sharc/                       ← Submodule: high-performance SQLite library

β”‚   β”œβ”€β”€ src/                     ← 9 project folders (Sharc, Sharc.Vector, etc.)

β”‚   β”œβ”€β”€ tests/                   ← 11 test projects (3,467 tests)

β”‚   β”œβ”€β”€ bench/                   ← BenchmarkDotNet suites

β”‚   └── docs/                    ← Architecture & feature docs

β”œβ”€β”€ CLAUDE.md                    ← AI assistant instructions

β”œβ”€β”€ README.md / README_CN.md     ← Documentation

└── sharpclaw.slnx               ← Solution file

```



---



## πŸ”§ Configuration



Configuration is stored in `~/.sharpclaw/config.json` (version 8):



```json

{

  "version": 8,

  "default": {

    "provider": "anthropic",

    "apiKey": "...",

    "model": "claude-3-5-sonnet-20241022"

  },

  "agents": {

    "main": { "enabled": true },

    "recaller": { "enabled": true },

    "saver": { "enabled": true },

    "summarizer": { "enabled": true }

  },

  "memory": {

    "embeddingProvider": "openai",

    "embeddingModel": "text-embedding-3-small"

  },

  "channels": {

    "web": { "address": "127.0.0.1", "port": 5000 }

  }

}

```



- **API keys** encrypted at rest with AES-256-GCM

- **Encryption key** stored in OS credential manager

- **Per-agent overrides** can specify different provider/model

- **ExtraRequestBody** supports custom fields (e.g., `thinking`)



---



## 🧩 Sharc Submodule



Sharpclaw includes [Sharc](https://github.com/revred/sharc.git) as a submodule β€” a high-performance, pure managed C# library for reading/writing SQLite files:



- **Pure managed C#** β€” zero native dependencies

- **609x faster** B-tree seeks than Microsoft.Data.Sqlite

- **Zero allocation** per-row reads via `Span`

- **Built-in features:** Encryption, Graph queries (Cypher), Vector search, SQL pipeline



See `sharc/README.md` and `sharc/CLAUDE.md` for details.



---



## πŸ“ License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



Copyright (c) 2025 sharpclaw.