🧠 MeshCtx

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

本地优先 · 跨会话记忆 · 断网可用 · 可审计发布 · 17脑区认知架构 · 11 语言

Quick Start · Why MeshCtx · Features · API · Contributing

---

🌍 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 (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)

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

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

Linux / WSL / macOS

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

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

Commands

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)

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

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

---

⭐ Star this repo if you find it useful!
_{Built with 🧠 by LucyAndLuna2023}