{"id":45400501,"url":"https://github.com/imxcstar/sharpclaw","last_synced_at":"2026-04-02T18:28:13.477Z","repository":{"id":339819937,"uuid":"1163482205","full_name":"imxcstar/sharpclaw","owner":"imxcstar","description":"AI agent with long-term memory, built on .NET 10. Supports Anthropic, OpenAI, and Gemini.","archived":false,"fork":false,"pushed_at":"2026-03-29T21:31:19.000Z","size":66305,"stargazers_count":21,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-29T22:22:08.537Z","etag":null,"topics":["ai","ai-agents","assistant","myclaw","nanobot","nullclaw","openclaw","picoclaw","zeroclaw"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imxcstar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-21T17:44:01.000Z","updated_at":"2026-03-29T21:24:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/imxcstar/sharpclaw","commit_stats":null,"previous_names":["imxcstar/sharpclaw"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/imxcstar/sharpclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imxcstar%2Fsharpclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imxcstar%2Fsharpclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imxcstar%2Fsharpclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imxcstar%2Fsharpclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imxcstar","download_url":"https://codeload.github.com/imxcstar/sharpclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imxcstar%2Fsharpclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","assistant","myclaw","nanobot","nullclaw","openclaw","picoclaw","zeroclaw"],"created_at":"2026-02-21T20:10:45.340Z","updated_at":"2026-04-02T18:28:13.468Z","avatar_url":"https://github.com/imxcstar.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐾 Sharpclaw\n\n[中文版](README_CN.md)\n\nSharpclaw 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**.\n\nBy 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.\n\n![Main Chat Window](preview/main.png)\n\n---\n\n## ✨ Key Features\n\n### 🧠 Multi-Tier Long-Term Memory System\n\n* **Three-Layer Pipeline:** Automatically manages context through Working Memory (current session) → Recent Memory (detailed summaries) → Primary Memory (consolidated core facts).\n* **Agentic Memory Saver:** An autonomous background agent actively decides what to save, update, or delete after each conversation turn.\n* **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).\n\n### 🛠️ System Operation Capabilities (Tools/Commands)\n\n* **File System:** Comprehensive file operations including searching, reading, appending, editing, and directory management.\n* **Process \u0026 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.\n* **Sandboxed Python:** Run Python code safely inside a WASM sandbox (see [WASM Python Sandbox](#-wasm-python-sandbox) below).\n\n### 🐍 WASM Python Sandbox\n\n* **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.\n* **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.\n* **Guaranteed Timeout:** Wasmtime's **epoch interruption** mechanism enforces a hard, non-bypassable execution timeout (default 180 s), preventing infinite loops and CPU exhaustion.\n* **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.\n* **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.\n\n### 📱 Multi-Channel Support\n\n* **TUI (Terminal.Gui):** A feature-rich terminal interface with collapsible logs, slash-command auto-completion, and configuration dialogs.\n* **Web (WebSocket):** A lightweight ASP.NET Core web server with a modern UI (Tokyo Night theme) and real-time streaming.\n* **QQ Bot:** Native integration with QQ channels, groups, and private messages.\n\n### 🔌 Extensible Skills System\n\n* **External Skills:** Load custom skills from `~/.sharpclaw/skills/` via `AgentSkillsDotNet`, seamlessly merged with built-in commands as a unified tool collection.\n\n### 🔒 Secure Configuration\n\n* Cross-platform secure credential storage (Windows Credential Manager, macOS Keychain, Linux libsecret) using AES-256-GCM encryption for API keys.\n* Automatic configuration version migration (up to v8).\n* Per-provider custom request body injection (e.g. `\"thinking\"`, `\"reasoning_split\"`) — configurable globally or per-agent via the Config Dialog.\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n* [.NET 10.0 SDK](https://dotnet.microsoft.com/)\n* Git (for cloning submodules)\n\n### Build and Run\n\n1. Clone the repository with its submodules:\n```bash\ngit clone --recursive https://github.com/yourusername/sharpclaw.git\ncd sharpclaw\n```\n\n2. Build the entire solution:\n```bash\ndotnet build\n```\n\n3. Run the application via the CLI. Sharpclaw routes the startup based on the command provided:\n\n* **Start Terminal UI (Default):**\n```bash\ndotnet run --project sharpclaw tui\n```\nFirst run automatically launches the configuration wizard:\n\n![Config Dialog](preview/config.png)\n\n* **Start Web Server:**\n```bash\ndotnet run --project sharpclaw web\n```\n\n![Web Chat Interface](preview/web.png)\n\n* **Start QQ Bot:**\n```bash\ndotnet run --project sharpclaw qqbot\n```\n\n* **Open Configuration UI:**\n```bash\ndotnet run --project sharpclaw config\n```\n\n---\n\n## 🏗️ Architecture\n\n### System Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  Frontend Layer (Channels/)                                  │\n│  ├── Tui/ — Terminal.Gui v2 (ChatWindow, ConfigDialog)      │\n│  ├── Web/ — ASP.NET Core WebSocket server                   │\n│  └── QQBot/ — QQ Bot integration (Luolan.QQBot)             │\n├─────────────────────────────────────────────────────────────┤\n│  Agent Layer (Agents/)                                       │\n│  ├── MainAgent — Conversation loop, tool orchestration      │\n│  ├── MemorySaver — Autonomous memory management             │\n│  └── ConversationArchiver — Two-phase memory consolidation  │\n├─────────────────────────────────────────────────────────────┤\n│  Memory Pipeline (Chat/, Memory/)                            │\n│  ├── MemoryPipelineChatReducer — Context window management  │\n│  ├── VectorMemoryStore — Sharc + SQLite vector search       │\n│  └── InMemoryMemoryStore — Keyword-based fallback           │\n├─────────────────────────────────────────────────────────────┤\n│  Skills \u0026 Commands (Commands/, ~/.sharpclaw/skills/)         │\n│  ├── Built-in — File, Process, HTTP, Task, System commands  │\n│  ├── External Skills — AgentSkillsDotNet plugin loading     │\n│  └── Memory Tools — SearchMemory, GetRecentMemories         │\n├─────────────────────────────────────────────────────────────┤\n│  WASM Python Sandbox (Services/, Interop/, libs/)            │\n│  ├── WasmtimePythonService — RunPython tool (primary)       │\n│  ├── WasmtimeWasiRuntime — Epoch-timeout WASM executor      │\n│  ├── WasmerWasiRuntime — Fallback WASM executor             │\n│  └── rustpython.wasm — Embedded Python 3 interpreter        │\n├─────────────────────────────────────────────────────────────┤\n│  Core Infrastructure (Core/)                                 │\n│  ├── AgentBootstrap — Shared initialization + skill loading │\n│  ├── SharpclawConfig — Configuration with encryption        │\n│  ├── ClientFactory — LLM client creation                    │\n│  ├── DataProtector/KeyStore — AES-256-GCM encryption        │\n│  └── TaskManager — Background process management            │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Memory System\n\nSharpclaw implements a sophisticated three-layer memory pipeline:\n\n| Layer | File | Purpose |\n|-------|------|---------|\n| **Working Memory** | `working_memory.json` | Current conversation snapshot |\n| **Recent Memory** | `recent_memory.md` | Detailed summaries (append-only) |\n| **Primary Memory** | `primary_memory.md` | Consolidated core facts |\n| **Vector Store** | `memories.db` | Semantic embeddings + metadata |\n| **History** | `history/*.md` | Archived full conversations |\n\n**Pipeline Flow:**\n1. After each turn → MemorySaver analyzes and updates vector store\n2. When context window overflows → Summarizer generates detailed summary → appends to recent memory\n3. When recent memory \u003e 30k chars → Consolidator extracts core info → overwrites primary memory\n\n### IChatIO Abstraction\n\nThe AI engine is decoupled from frontend through `IChatIO` interface:\n- **TUI:** `Channels/Tui/ChatWindow.cs` — Terminal.Gui v2 interface\n- **Web:** `Channels/Web/WebSocketChatIO.cs` — WebSocket frontend\n- **QQ Bot:** `Channels/QQBot/QQBotServer.cs` — QQ Bot interface\n\nAll frontends share the same `MainAgent` logic.\n\n---\n\n## 🛡️ WASM Python Sandbox\n\nSharpclaw 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.\n\n### Runtime Stack\n\n| Component | Technology | Role |\n|-----------|-----------|------|\n| **Python Interpreter** | [RustPython](https://github.com/RustPython/RustPython) compiled to WASM | Python 3 runtime inside sandbox |\n| **Primary Runtime** | [Wasmtime](https://wasmtime.dev/) v43 | WASM executor with epoch-based timeout |\n| **Fallback Runtime** | [Wasmer](https://wasmer.io/) | Alternative executor |\n| **System Interface** | WASI | Capability-based filesystem \u0026 I/O abstraction |\n\n### Security Boundaries\n\n| Boundary | Mechanism | Effect |\n|----------|-----------|--------|\n| **Filesystem** | WASI pre-opened directories | Only `/workspace` and a per-run `/sharpclaw_tmp` are accessible |\n| **Memory** | WASM linear memory | Complete isolation from host process memory |\n| **Execution Time** | Wasmtime epoch interruption | Hard, non-bypassable timeout (default 180 s) |\n| **I/O** | WASI syscall-level callbacks | Output captured before reaching the host shell |\n| **Concurrency** | `SemaphoreSlim` mutex | One Python execution at a time, preventing races |\n| **State** | Fresh WASM instance per run | No shared state between invocations |\n\n### Execution Flow\n\n```\nAgent calls RunPython(code, purpose, timeoutSeconds)\n  │\n  ▼\nWasmtimePythonService (acquires mutex)\n  │\n  ▼\nWasmtimeWasiRuntime.ExecuteCode()\n  ├── Create isolated temp dir  (GUID-named, auto-deleted on finish)\n  ├── Write user code to temp file\n  ├── Init Wasmtime engine (epoch interruption enabled)\n  ├── Configure WASI:\n  │     ├── Pre-open /workspace  (rw)\n  │     ├── Pre-open /sharpclaw_tmp  (rw)\n  │     ├── Capture stdout/stderr via native callbacks\n  │     └── Set env vars (PWD=/workspace only)\n  ├── Instantiate rustpython.wasm  +  call _start\n  ├── Start timeout watchdog (Task.Delay → increment epoch)\n  └── Return WasmCommandResult { Success, ExitCode, StdOut, StdErr, TimedOut }\n```\n\n### Capability Matrix\n\n| Capability | Status | Notes |\n|-----------|--------|-------|\n| Standard Python library | ✅ | Frozen into rustpython.wasm |\n| File I/O in `/workspace` | ✅ | Maps to the agent's working directory on the host |\n| Arbitrary computation | ✅ | No restrictions beyond timeout |\n| Host filesystem (outside workspace) | ❌ | Blocked by WASI capability model |\n| Native extensions (`.so`/`.dll`) | ❌ | WASM cannot load host shared libraries |\n| Spawning host processes | ❌ | No `subprocess`/`os.system` to host |\n| Unrestricted network access | ❌ | No WASI socket mapping by default |\n\n---\n\n## 📁 Project Structure\n\n```\nsharpclaw/\n├── sharpclaw/                   ← Main project\n│   ├── Program.cs               ← Entry point (tui/web/qqbot/config)\n│   ├── sharpclaw.csproj         ← Project file (net10.0)\n│   ├── Abstractions/            ← IChatIO, IAppLogger interfaces\n│   ├── Agents/                  ← MainAgent, MemorySaver, ConversationArchiver\n│   ├── Channels/                ← Tui, Web, QQBot frontends\n│   ├── Chat/                    ← MemoryPipelineChatReducer\n│   ├── Clients/                 ← DashScopeRerankClient, ExtraFieldsPolicy\n│   ├── Commands/                ← All tool implementations\n│   ├── Core/                    ← Config, Bootstrap, TaskManager\n│   ├── Memory/                  ← IMemoryStore, VectorMemoryStore\n│   ├── UI/                      ← ConfigDialog, AppLogger\n│   └── wwwroot/                 ← Web UI (index.html)\n├── preview/                     ← Screenshots\n├── sharc/                       ← Submodule: high-performance SQLite library\n│   ├── src/                     ← 9 project folders (Sharc, Sharc.Vector, etc.)\n│   ├── tests/                   ← 11 test projects (3,467 tests)\n│   ├── bench/                   ← BenchmarkDotNet suites\n│   └── docs/                    ← Architecture \u0026 feature docs\n├── CLAUDE.md                    ← AI assistant instructions\n├── README.md / README_CN.md     ← Documentation\n└── sharpclaw.slnx               ← Solution file\n```\n\n---\n\n## 🔧 Configuration\n\nConfiguration is stored in `~/.sharpclaw/config.json` (version 8):\n\n```json\n{\n  \"version\": 8,\n  \"default\": {\n    \"provider\": \"anthropic\",\n    \"apiKey\": \"...\",\n    \"model\": \"claude-3-5-sonnet-20241022\"\n  },\n  \"agents\": {\n    \"main\": { \"enabled\": true },\n    \"recaller\": { \"enabled\": true },\n    \"saver\": { \"enabled\": true },\n    \"summarizer\": { \"enabled\": true }\n  },\n  \"memory\": {\n    \"embeddingProvider\": \"openai\",\n    \"embeddingModel\": \"text-embedding-3-small\"\n  },\n  \"channels\": {\n    \"web\": { \"address\": \"127.0.0.1\", \"port\": 5000 }\n  }\n}\n```\n\n- **API keys** encrypted at rest with AES-256-GCM\n- **Encryption key** stored in OS credential manager\n- **Per-agent overrides** can specify different provider/model\n- **ExtraRequestBody** supports custom fields (e.g., `thinking`)\n\n---\n\n## 🧩 Sharc Submodule\n\nSharpclaw includes [Sharc](https://github.com/revred/sharc.git) as a submodule — a high-performance, pure managed C# library for reading/writing SQLite files:\n\n- **Pure managed C#** — zero native dependencies\n- **609x faster** B-tree seeks than Microsoft.Data.Sqlite\n- **Zero allocation** per-row reads via `Span\u003cT\u003e`\n- **Built-in features:** Encryption, Graph queries (Cypher), Vector search, SQL pipeline\n\nSee `sharc/README.md` and `sharc/CLAUDE.md` for details.\n\n---\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 sharpclaw.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimxcstar%2Fsharpclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimxcstar%2Fsharpclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimxcstar%2Fsharpclaw/lists"}