Metadata-Version: 2.4
Name: meshctx
Version: 3.137.8
Summary: World's First Self-Evolving Agent System
Author-email: Jason Liu <jason.liu@meshctx.com>
License-Expression: AGPL-3.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.104.1
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: openai>=1.6.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: black>=23.11.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: python-multipart>=0.0.6; extra == "dev"
Requires-Dist: requests>=2.31.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Requires-Dist: openai>=1.6.0; extra == "dev"
Provides-Extra: llm
Requires-Dist: openai>=1.6.0; extra == "llm"
Provides-Extra: vector
Requires-Dist: chromadb>=0.4.22; extra == "vector"
Requires-Dist: sentence-transformers>=2.2.2; extra == "vector"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/logo.png" alt="MeshCtx" width="200">
  <h1 align="center">🧠 MeshCtx</h1>
  <h3 align="center">The agent that remembers you — fully local, fully offline, fully auditable.</h3>
  <h3 align="center">本地优先 · 跨会话记忆 · 断网可用 · 可审计发布 · 17脑区认知架构 · 11 语言</h3>
</p>

<p align="center">
  <a href="LEGAL.md"><img src="https://img.shields.io/badge/license-AGPLv3+Commercial-blue"></a>
  <a href="#"><img src="https://img.shields.io/badge/python-3.10+-green"></a>
  <a href="#"><img src="https://img.shields.io/badge/tests-4014-brightgreen"></a>
  <a href="#"><img src="https://img.shields.io/badge/core_modules-313-purple"></a>
  <a href="#"><img src="https://img.shields.io/badge/brain_regions-17-orange"></a>
  <a href="#"><img src="https://img.shields.io/badge/papers-3-blue"></a>
  <a href="https://github.com/LucyAndLuna2023/meshctx/stargazers"><img src="https://img.shields.io/github/stars/LucyAndLuna2023/meshctx?style=social"></a>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> ·
  <a href="#-why-meshctx">Why MeshCtx</a> ·
  <a href="#-core-features">Features</a> ·
  <a href="#-api">API</a> ·
  <a href="#-contributing">Contributing</a>
</p>

---

## 🌍 Why MeshCtx?

**The agent that remembers you — fully local, fully offline, fully auditable.**

**The problem: your local AI has amnesia.** Ollama gives you a great local model — that remembers nothing between chats. Every session starts from zero.

**MeshCtx gives it a memory that lives on your disk.** Tell it once — *"I'm allergic to peanuts"*, *"my report is due every Friday"* — and it still knows weeks later. Across restarts. With the network unplugged.

```
$ meshctx chat
You: Remember — allergic to peanuts, prefers morning meetings.
MeshCtx: Noted. Stored locally, encrypted at rest.

  … three weeks later, after a reboot, Wi-Fi off …

You: Suggest a lunch spot for the client visit tomorrow.
MeshCtx: Three options near their office — all with peanut-free menus. Also, it's a Friday: your weekly report is due.
```

### Verified in this repo

- 🔓 **Local-First, Zero Login** — runs on your machine. No account, no cloud auth, no phone-home. (Most cloud agents require online verification even for local models.)
- 📴 **Offline-Capable** — point MeshCtx at [Ollama](https://ollama.com) (`ollama:qwen3` / `ollama:llama3.3` presets built in) or any OpenAI-compatible local endpoint, and keep working with the network unplugged.
- 🧠 **Cross-Session Memory** — retrieval-injected, on-disk local memory (`src/chat_tools.py :: _collect_memory_entries`). Survives restarts. Never leaves your disk.
- 🔍 **Auditable Releases** — every release passes a 3,900+ test gated suite plus a multi-party AI audit with SHA256 evidence per tag.
- 🌍 **11 Languages** — full UI i18n, parity-checked dictionaries (1,592 keys × 11 languages).

### Design philosophy: a cognitive architecture, not a stateless tool

| Feature | Typical Agent | MeshCtx |
|---------|--------------|---------|
| Memory | Vector store lookup | Hippocampal replay + emotional weighting + pattern chunking |
| Planning | Single-pass chain | Free energy principle + active inference + thalamic gating |
| Self-improvement | None | Genomic optimizer (genetic algorithm on own parameters) |
| Code modification | Static | Neural plasticity-inspired self-modifying code at runtime |
| Architecture | Flat modules | 17 brain regions simulating cortical-subcortical loops |

MeshCtx treats AI agent design as a **neuroscience problem**, not just an engineering problem.

---

## 🔓 Open Source / Closed Core Architecture

| Repo | Visibility | Content |
|------|-----------|---------|
| **meshctx** (this repo) | 🔓 Public | Security modules (full impl) + **313 core modules — 311 with real implementations** (Kernel · SuperBrain · Sandbox · Memory · CognitiveLoop …), 2 interface stubs |
| **meshctx-core** | 🔒 Private | Optional enhanced/enterprise layer (plugin registration, ResourceManager, enterprise base) — absent install degrades gracefully |

**For developers**: `src/core/*.py` contains complete interface definitions. Use `from src.core.agent_swarm import AgentIdentity` for type-safe integration.

**Commercial**: `pip install meshctx-core` (private repo, license required) — zero code changes needed.

---

## 🚀 Quick Start

### Fully offline in 2 minutes (Ollama)

```bash
ollama serve & ollama pull qwen3
# Start MeshCtx, open Model Hub → Add Model → preset `ollama:qwen3` (http://127.0.0.1:11434/v1)
# …unplug the network. Chat, memory, tools keep working — 100% on your machine.
```

### Windows
```powershell
# Download installer (recommended)
# https://github.com/LucyAndLuna2023/meshctx/releases/latest
# meshctx-setup.exe — NSIS wizard, 7 languages, one-click install
```

### Linux / WSL / macOS
```bash
curl -fsSL https://raw.githubusercontent.com/LucyAndLuna2023/meshctx/main/install.sh | bash
meshctx setup    # Configure API keys
meshctx start    # Start web service (http://localhost:3001)
```

> macOS 专用脚本: `curl -fsSL .../install-mac.sh | bash`。
> 安装脚本默认英文显示；Windows 安装器 (NSIS) 支持 10 语言: zh/en/ja/ko/fr/de/es/it/ar/he。中文用户可显式切回: `MESHCTX_LANG=zh ./install.sh`（macOS 同理 `MESHCTX_LANG=zh ./install-mac.sh`；Windows 同理 `set MESHCTX_LANG=zh && install.bat`）。

> 组织治理环境变量 (v3.126.0, org×plan 配置化上限, 默认不设限):
> - `MESHCTX_ORG_MAX_DEPTS` — 组织部门数上限 (整型>0; 空/0=不设限)。超限: 单建返回 400, 批量导入条目软失败。
> - `MESHCTX_ORG_MAX_MEMBERS` — 组织成员数上限 (整型>0; 空/0=不设限)。超限: 新成员分配返回 400。
> 可观测性: `MESHCTX_OTLP_ENDPOINT` 开启 OTLP 导出 (默认关)。

### From Source
```bash
git clone https://github.com/LucyAndLuna2023/meshctx.git
cd meshctx && pip install -e .
meshctx chat     # CLI mode
```

### Commands
```bash
meshctx start          # Web service (default http://localhost:3001)
meshctx chat           # CLI conversation
meshctx setup          # Configure API keys and models
meshctx desktop        # Windows desktop client
meshctx agent          # Multi-step autonomous agent
```

---

## 🧠 Core Features

### 🧬 GenomicOptimizer (v3.116) 🆕
Genetic algorithm that evolves agent's own parameters: temperature, top_p, prompt style, memory weights.
- Gaussian mutation · transposon-style jumps · crossover · elitist selection · niche protection
- ~784 lines, zero dependencies, thread-safe, outperforms manual tuning in ~10 generations

### 🔍 Observability Tracing (v3.116) 🆕
- Span/TraceLogger: llm · tool · chain full pipeline tracing
- Thread-safe (RLock) + optional JSONL disk export

### 🔄 RAG Query Rewriting + RRF Fusion (v3.116) 🆕
- Multi-path rewriting (synonym/sub-question/expansion) + Reciprocal Rank Fusion reranking

### 🛡️ Terminal Security Sandbox (v3.116) 🆕
- Session continuity + 3-tier danger classification (normal/dangerous/critical)
- Dangerous command interception, critical commands require approval

### 🧠 Brain-Inspired Cognitive Architecture
- **17 brain regions**: Free energy principle · active inference · global workspace · homeostasis
- **Hybrid reasoning**: Free energy-driven exploration vs fast-path decisions
- **SuperBrain**: Hippocampal replay · amygdala emotional tagging · default mode network · thalamic gating
- **Metacognition**: Self-evaluation · error classification · behavior adjustment

### 🧩 Human-Like Memory System (v2.40)
```
Traditional AI: Store → Keyword match
MeshCtx:       Pattern chunking → Emotional weighting → Hippocampal replay → Associative spread
```
- **Pattern chunking**: Compress raw data into meaning patterns (like a chess player recognizing formations)
- **Emotional weighting**: CRITICAL memories decay 200x slower than routine
- **Hippocampal replay**: Background 5-min cycle consolidates memories + discovers associations
- **Reconsolidation**: Each recall updates the memory (core human learning mechanism)
- **Associative spread**: Weighted link propagation (smell → scene → person → conversation)
- **Adaptive forgetting**: Forget details, keep patterns — forgetting is a feature, not a bug
- **FSRS spaced repetition** (phase-1): Per-memory stability/difficulty (D/S/R) state machine schedules every recall at the edge of forgetting — reviews land exactly when retrieval is about to fail, cutting injection tokens while maximizing retention
- **Active recall write-back**: Every hit + confirmation rewrites stability and re-schedules the next review (test-effect / retrieval practice theory); forgetful lapses are punished with a stability halving
- **CMA-ES self-tuning** (phase-1): Continuous parameters (temperature / top_p / memory weights / FSRS weights) optimized via covariance-matrix-adaptation evolution — replaces blind GA mutation with gradient-free global optimization

### 🐝 Agent Swarm — Manager-Worker Multi-Agent (v3.34)
```bash
meshctx start --port 3001  # Manager node

# Register worker on another machine
curl -X POST http://manager:3001/swarm/register \
  -d '{"worker_id":"bot1","name":"Coder","capabilities":["code"]}'

# Submit complex task — auto-decompose → dispatch → parallel execute
curl -X POST http://manager:3001/swarm/execute \
  -d '{"task":"Research best practices + write code + review","type":"research"}'
```
- Manager-Worker architecture with network + key-based coordination
- Auto task decomposition: research/code/analysis/report templates
- Identity auth: ed25519 + HMAC + 5-min anti-replay
- Collaboration: Delegate · Vote · Consensus · Ensemble

### 🌐 Multi-Platform Gateway (v2.39)
WeChat Enterprise · Feishu · Telegram · Slack · Discord · WhatsApp

### 📊 Usage Insights (v2.38)
Per day/week/month tracking: sessions · messages · tokens · latency · error rate

### 🔄 Credential Pool Rotation (v2.37)
Multi-API key rotation: round_robin · least_used · random · auto-exhaustion detection

---

## 📊 Version History

| Version | Highlights | Tests |
|---------|-----------|-------|
| v2.37 | Credential pool rotation | 825 |
| v2.40 | **Human-like memory** (6 mechanisms) | 916 |
| v2.41 | **Self-healing ops engine** | 935 |
| v2.42 | **Hooks engine** (8 events, Claude Code parity) | 956 |
| v3.115 | **DeepSeek TUI competitor** (14 modules, 4200 lines) | 130 |
| v3.116 | **Open-source agent framework** (RAG+RRF, Sandbox, GenomicOptimizer, Observability) | **3404** |

---

## 🏗️ Architecture

```
meshctx/
├── src/
│   ├── main.py              # FastAPI main app
│   ├── web_ui.py            # Web UI templates
│   ├── cli.py               # CLI commands
│   ├── i18n.py              # 10-language i18n
│   └── core/                # Core modules
│       ├── hybrid_reasoning.py  # Free energy reasoning
│       ├── observability.py     # Span/TraceLogger
│       ├── rag_orchestrator.py  # RAG + RRF fusion
│       ├── terminal_sandbox.py  # Security sandbox
│       ├── genomic_optimizer.py # Genetic algorithm engine
│       ├── memory_v5.py         # 4-tier memory injection
│       └── ...                  # 14 modules total
├── tests/                   # 3404 tests
├── docs/                    # Documentation site
└── install.sh               # One-click install
```

---

## 🔌 API

### Chat
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/chat` | POST | Conversation (JSON) |
| `/api/chat/stream` | POST | Streaming (SSE) |

### Dual Session (Planner-Executor)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/dual/plan` | POST | Planner planning |
| `/api/dual/execute` | POST | Executor execution |
| `/api/dual/stats` | GET | Session stats |

### Memory
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/memory/stats` | GET | Memory diagnostics |
| `/api/memory/add` | POST | Add memory |
| `/api/memory/search` | POST | Search memories |

### Agent Swarm
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/swarm/register` | POST | Register worker |
| `/swarm/execute` | POST | Submit swarm task |
| `/swarm/status` | GET | Swarm status |

### Subagent
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/subagent/run` | POST | Launch isolated subagent |
| `/api/subagent/{id}/status` | GET | Query status |

---

## 🔒 Security

- **Secret scanning**: Auto-detect and redact API keys/tokens/PII
- **Hooks interception**: Block dangerous commands by default
- **Credential pool**: Key rotation prevents exhaustion
- **Approval modes**: YOLO / smart / manual three-tier

---

## 🌐 Platform Support

| Platform | Install | Status |
|----------|---------|--------|
| Windows | NSIS installer (10 languages) | ✅ |
| Linux | curl\|bash script | ✅ |
| macOS | DMG + Homebrew | ✅ |
| WSL | Same as Linux | ✅ |
| Docker | docker-compose | ⚠️ WIP |

---

## 🤝 Contributing

We welcome contributions! Here's how:

1. **Fork** this repo
2. **Create** a feature branch: `git checkout -b feature/amazing-thing`
3. **Commit** with conventional commits: `feat: add thalamic gating filter`
4. **Test**: `python -m pytest tests/ -x`
5. **Push** and open a **Pull Request**

### Good First Issues
- 🧠 Add new brain region simulations
- 🔌 New platform gateway connectors
- 📊 Dashboard visualizations
- 🐛 Bug fixes and test coverage

### Development Setup
```bash
git clone https://github.com/LucyAndLuna2023/meshctx.git
cd meshctx
pip install -e ".[dev]"
python -m pytest tests/ -x
```

---

## 📄 License

- **Framework layer**: AGPLv3 Open Source
- **Core brain layer**: Source visible · **Free for individuals and teams of up to 5 people** · Commercial license required for organization/commercial use
- Contact: license@meshctx.com

---

<p align="center">
  <b>⭐ Star this repo if you find it useful!</b><br>
  <sub>Built with 🧠 by <a href="https://github.com/LucyAndLuna2023">LucyAndLuna2023</a></sub>
</p>
