v0.1.0 In Development In Entwicklung 开发中 MIT License Mantis Family Mantis-Familie Mantis 家族 AAMS v1.3.0

MantisClaw

Autonomous Agent Loop Framework — local-first, emergent identity

Autonomes Agenten-Loop-Framework — local-first, emergente Identität

自主代理循环框架 — 本地优先，涌现身份

soul(t) = f(base, agenda.resolve(account, social, decentral), working_context) Emergent soul computation — never written, recalculated every tick Emergente Soul-Berechnung — nie geschrieben, bei jedem Tick neu berechnet 涌现灵魂计算 — 从不写入，每次心跳重新计算
GitHub AAMS Standard Mantis-OS
// Architecture

Three Layers. One Consciousness.

Drei Schichten. Ein Bewusstsein.

三层架构，一个意识。

core/
Brain & Loop — L3
Gehirn & Loop — L3
大脑 & 循环 — L3
  • runtime.py
  • planner.py
  • executor.py
  • observer.py
  • reflect.py
  • context.py
  • skill_executor.py
  • llm.py · session.py · ltm.py
  • registry/ → tools/
identity/
Emergent Identity — L1
Emergente Identität — L1
涌现身份 — L1
  • base.md
  • agenda.md
  • account.md
  • social.md
  • decentral.md
  • hook.md
WORKSPACE/WORKING/
AAMS Body — L2
  • PROJECT/
  • WORKPAPER/
  • WHITEPAPER/
  • MEMORY/ · DIARY/
  • GUIDELINES/
  • SCIENCE/
  • LOGS/ · TOOLS/skills/
// Layer Model

L0 – L5: Each Layer Has a Purpose.

L0 – L5: Jede Schicht hat eine Aufgabe.

L0 – L5：每层各司其职。

L0
LLM Backend
core/llm.py
LM Studio · Ollama
Cloud optional
L1
Identity
identity/
soul(t)
L2
AAMS Body
WORKING/
passive — tools only
WORKING/
passiv — nur über Tools
WORKING/
被动 — 仅通过工具
L3
Runtime / Loop
planner · executor
observer · reflect
L4
Tool Registry
core/registry/
Whitelist · Fuzzy-Resolve
L5
Security
Cross-cutting
Security level per tool
Querschnitt
Security-Level pro Tool
横切关注
每个工具的安全级别

Core rule: L3 (Loop) never touches L2 (Body) directly — all access to WORKING/ goes through a registered Tool in L4. Kernregel: L3 (Loop) berührt L2 (Körper) nie direkt — jeder Zugriff auf WORKING/ läuft über ein registriertes Tool in L4. 核心规则：L3（循环）从不直接访问 L2（主体）— 所有对 WORKING/ 的访问都通过 L4 中已注册的工具。

// The Loop

tick() — The Heartbeat

tick() — Das Herzstück

tick() — 心跳核心

L1
Compute Identity & Soulsoul(t) = f(base, agenda, ctx) Identität & Soul berechnensoul(t) = f(base, agenda, ctx) 计算身份与灵魂soul(t) = f(base, agenda, ctx)
L4
Load Context (JIT)workpapers · memory · project Kontext laden (JIT)Workpapers · Memory · Projekt 加载上下文（JIT）工作文档 · 记忆 · 项目
Plan
Planner generates planGOAL → REASONING → STEP 1..N Planner erzeugt PlanGOAL → REASONING → STEP 1..N 规划器生成计划GOAL → REASONING → STEP 1..N
Execute
Executor runs stepsEach step → tool call via Registry Executor führt Steps ausJeder Step → Tool-Call via Registry 执行器运行步骤每步 → 通过注册表调用工具
Observe
Observer evaluates resultsok / fail / anomalies → history Observer bewertet Ergebnisseok / fail / Anomalien → History 观察器评估结果成功 / 失败 / 异常 → 历史
Reflect
Reflection Loop (RFL)Self-evaluation → guidelines → improve Reflection Loop (RFL)Selbstbewertung → Guidelines → verbessern 反思循环（RFL）自我评估 → 指南 → 改进
Sleep
Heartbeat wait (60s)Idle detection after 3 identical plans Heartbeat-Pause (60s)Idle Detection nach 3 identischen Plänen 心跳等待（60秒）3次相同计划后进入空闲检测
core/runtime.py
async def tick(self): # 1. Identity & Soul soul = self.identity.compute_soul() # 2. Context (JIT) ctx = await self.context.load() # 3. Plan plan = await self.planner.plan( soul, ctx, self.registry ) # 4. Execute results = await self.executor.run( plan, self.registry ) # 5. Observe self.observer.evaluate(results) # 6. Reflect (RFL) await self.reflector.reflect( results, self.observer )
// Working System — AAMS v1.3.0

Eight Memory Layers. Epistemic Hygiene.

Acht Memory-Schichten. Epistemische Hygiene.

八层记忆系统，认知卫生。

PROJECT/
Strategic Memory
What am I working on?Scope · Goals · Milestones
_active.yaml → max 1 active Woran arbeite ich?Scope · Goals · Milestones
_active.yaml → max 1 aktiv 我在做什么？范围 · 目标 · 里程碑
_active.yaml → 最多1个活跃
WORKPAPER/
Working Memory
What am I doing now?One file per session
open → work → close → archived Was tue ich jetzt?Eine Datei pro Session
open → work → close → archived 我现在在做什么？每次会话一个文件
打开 → 工作 → 关闭 → 归档
WHITEPAPER/
Semantic Memory (stable)
Semantic Memory (stabil)
语义记忆（稳定）
How is the system built?CORE · IDENTITY · WORKING · TOOLS Wie ist das System aufgebaut?CORE · IDENTITY · WORKING · TOOLS 系统如何构建？CORE · IDENTITY · WORKING · TOOLS
MEMORY / LTM
Semantic Memory (learned)
Semantic Memory (gelernt)
语义记忆（习得）
What have we learned?ltm-index.md · optional ChromaDB
Ingested from closed workpapers Was haben wir gelernt?ltm-index.md · optional ChromaDB
Ingestiert aus geschlossenen WPs 我们学到了什么？ltm-index.md · 可选 ChromaDB
从已关闭的工作文档中提取
DIARY/
Temporal Index
When was what touched?Pointer-only · max 3 entries/day
YYYY-MM.md monthly files Wann wurde was angefasst?Pointer-only · max 3 Einträge/Tag
YYYY-MM.md monatliche Dateien 什么时候做了什么？仅指针 · 每天最多3条
YYYY-MM.md 月度文件
GUIDELINES/
Procedural Memory
How do I work best?Observer extracts lessons
Grows with every session Wie arbeite ich am besten?Observer extrahiert Lektionen
Wächst mit jeder Session 最佳工作方式？观察器提取经验
每次会话后增长
SCIENCE/
Epistemic Layer
Epistemische Schicht
认知层
Is this correct? Where do we stand?research · validate · hypothesize
Own solution vs. state-of-the-art Stimmt das? Wo stehen wir?research · validate · hypothesize
Eigene Lösung vs. State-of-the-Art 这正确吗？我们在哪里？研究 · 验证 · 假设
自有方案 vs. 最前沿
TOOLS/skills/
Skill Orchestration — L5
Skill-Orchestrierung — L5
技能编排 — L5
How do I combine tools?Markdown + YAML workflows
Multi-step processes as skills Wie kombiniere ich Tools?Markdown + YAML Workflows
Multi-Step Prozesse als Skill 如何组合工具？Markdown + YAML 工作流
多步骤流程作为技能

Knowledge chain (strict): Workpaper → Whitepaper → LTM — fleeting ideas become architecture, then long-term memory. Whitepaper > Guideline on conflict. Wissenskette (strikt): Workpaper → Whitepaper → LTM — flüchtige Ideen werden erst Architektur, dann Langzeitgedächtnis. Whitepaper > Guideline bei Konflikt. 知识链（严格）：工作文档 → 白皮书 → 长期记忆 — 临时想法先成为架构，再成为长期记忆。白皮书 > 指南（冲突时）。

// Web Dashboard

localhost:8080 — Real-time Agent Insight.

localhost:8080 — Echtzeit-Einblick in den Agenten.

localhost:8080 — 实时代理洞察。

Left — Agent Status
Links — Agent Status
左侧 — 代理状态
L1 · Core (Backend/Model)
L2 · Identity / soul(t)
L3 · Runtime (Live Ticks)
L4 · Tools (Project + Core)
Center — Chat (SSE Token Streaming)
Mitte — Chat (SSE Token-Streaming)
中间 — 对话（SSE Token 流）
> What is the current project status?
MantisClaw: Active project: MantisClaw Core. 9/11 milestones done. Current focus: Project-Scoped AAMS architecture.
Token-by-token via SSE · Model switcher: LM Studio ↔ Ollama live Token-by-Token via SSE · Model-Switcher: LM Studio ↔ Ollama live 逐Token通过SSE · 模型切换：LM Studio ↔ Ollama 实时
Right — Knowledge
Rechts — Wissen
右侧 — 知识
R1 · Chat History
R2 · Project (Milestones)
R3 · Workpapers
R4 · Workspace
uvicorn dashboard.app:app --reload --port 8080
// Quick Start

Five Steps to a Running Agent.

In fünf Schritten zum laufenden Agenten.

五步启动代理。

01
Clone Repo
Repo klonen
克隆仓库
git clone https://github.com/DEVmatrose/MantisClaw cd MantisClaw
02
Virtualenv
python -m venv .venv source .venv/bin/activate pip install -r requirements.txt
03
Configuration
Konfiguration
配置
cp config/.env.example .env

LLM_BACKEND=lmstudio (default)
Optional: OPENAI_API_KEY, ANTHROPIC_API_KEY

04
Set Up Identity
Identität einrichten
设置身份
cp identity/base.md.example identity/base.md cp identity/agenda.md.example identity/agenda.md

Optional: account, social, decentral, hook

05
Start LLM & Agent
LLM & Agent starten
启动 LLM & 代理
# LM Studio: Server on :1234 # or Ollama: ollama serve ollama run qwen3-coder python -m core.runtime
// Integration

Standalone or Part of Mantis-OS.

Standalone oder Teil von Mantis-OS.

独立运行或集成至 Mantis-OS。

Standalone
MantisClaw
Brain + Identity + AAMS Body. Single repo, runs standalone. Local-first, no cloud required. The code is identical with MantisClaw in Mantis-OS. Gehirn + Identität + AAMS Body. Einzelnes Repo, eigenständig lauffähig. Local-first, kein Cloud-Zwang. Der Code ist identisch mit MantisClaw in Mantis-OS. 大脑 + 身份 + AAMS 主体。单一仓库，独立运行。本地优先，无需云端。代码与 Mantis-OS 中的 MantisClaw 完全一致。
+
Optional
MantisNostr
Mesh network layer. L6 Network. Agents communicate via the Nostr protocol in a decentralized mesh. Mesh-Netzwerk Layer. L6 Network. Agenten kommunizieren über das Nostr-Protokoll in einem dezentralen Mesh. 网格网络层。L6 网络。代理通过 Nostr 协议在去中心化网格中通信。
=
Complete Node Vollständiger Knoten 完整节点
Mantis-OS
Autonomous agent operating system. MantisClaw as brain, MantisNostr as nervous system. Only the integration differs. Autonomes Agenten-Betriebssystem. MantisClaw als Gehirn, MantisNostr als Nervensystem. Nur die Integration unterscheidet sich. 自主代理操作系统。MantisClaw 为大脑，MantisNostr 为神经系统。只有集成方式不同。