English | 简体中文

🔮 Negentropy

An agentic system built on a "One Root, Five Wings" architecture, dedicated to combating the entropy production of infomation and forging a continuously self-evolving cognitive framework.

🔮 The Self · Scheduling Core | Bypasses atomic task execution. Strictly adhering to Orthogonal Decomposition, it acts as the master conductor, assigning intents to the most capable faculties.
👁️ The Eye · Perception | 💎 The Soul · Internalization | 🧠 The Mind · Contemplation | ✋ The Hand · Action | 🗣️ The Voice · Influence

---

Disclaimer · All tools and methodologies provided by this project are for reference only. The project team bears no direct or indirect responsibility for the outcomes of using this system. The term "cultivation/practice" herein refers purely to the self-evolution and optimization of the system, free of any religious connotations.

---

🤔 Why Negentropy Engine?

You've probably test-driven your fair share of agentic systems by now, and inevitably stepped into these classic pitfalls:

• 🌀 Information Overload —— Agents devour oceans of data, but signal and noise fly together. You're left with a pile of "truthful nonsense."
• 🕳️ Goldfish Memory —— The hard-won conclusions from your last dialogue are tossed out the window by the next. It's like rebooting life every five minutes.
• 🏄 Surface-Level Skimming —— Agents give you textbook answers but never dig into second-order problems. Nobody's ever asking "But why?" on your behalf.
• 💬 Armchair Strategists —— The analysis is flawless, but the moment real work (executing code, touching files) is required, you hit the dreaded "I suggest you do this manually."
• 🌫️ Impenetrable Jargon —— What should be a professional insight reads like an ancient scroll. The value degradation in transmission approaches a solid 80%.

Negentropy's Answer: We engage these entropic forms head-on. The goal isn't just to build another Agent, but to forge a continuously self-evolving cognitive system.

_{Diagram source (diff-able text): readme--faculties-en.mmd · Interactive version (open locally): readme--faculties-en.html}

---

✨ Core Features

• 🏗️ "One Root, Five Wings" Orchestration —— A master orchestrator teaming up with five orthogonal faculties. The root agent handles the dispatching, while the five wings systematically obliterate information overload, amnesia, superficiality, inaction, and obscurity.

• 🔄 Three Standardized Pipelines —— Pre-packaged pipelines for Knowledge Acquisition, Problem Solving, and Value Delivery. Say goodbye to the tedious chore of manually wiring multi-step tasks. It works out of the box.

• 🧠 Dynamic Memory System —— A memory decay mechanism modeled on the Ebbinghaus Forgetting Curve, paired with structured factual storage and memory governance. This ensures the Agent actually remembers instead of merely repeating.

• 📚 Knowledge Management Engine —— From document ingestion, semantic chunking, and vector retrieval to knowledge graphs and semantic search—a full-lifecycle knowledge management suite.

• 🐱 Sandboxed Code Execution —— Dual-channel isolated execution via MCP Protocol + MicroSandbox. Safely allows the Agent to get its hands dirty, graduating from "all talk" to "taking action."

• 🔧 Pluggable Backends —— Sessions, Memories, Artifacts, and Credentials fully support seamless switching between in-memory / PostgreSQL / VertexAI / GCS. Use in-memory for dev, Postgres for prod. Zero-code smooth migration.

• 📡 Full-Stack Observability —— Structured logging via structlog + Distributed tracing with OpenTelemetry + Trace analysis via Langfuse. Every "thought" the Agent has is fully documented and auditable.

---

✨ Quick Start

One command brings up the full stack (postgres + perceives + backend + ui + wiki) with zero cloud credentials required to boot. LLM chat is activated by one of OpenAI / Anthropic / Gemini API keys; for a fully local, zero-key setup, see Local LLM (Ollama).

Prerequisites

Dependency	Minimum Version	Purpose
Docker Engine + Compose v2	Engine 24+ · Compose 2.24+	One-click launch (includes the database)
or (native path) Python · uv · Node.js · pnpm	3.13 · latest · 22+ · latest	Hot-reload without Docker

The Docker path needs no local PostgreSQL. The native path needs a pgvector-enabled Postgres (see Development Guide). mise / asdf users get the right Python & Node automatically via the root .tool-versions.

A. One-click (Docker, recommended)

git clone https://github.com/ThreeFish-AI/negentropy.git
cd negentropy
./scripts/dev            # = setup + build & start the full stack + health self-check

./scripts/dev automatically: creates .env.docker.local, layers local-safe config, builds & starts 5 containers, polls backend /health, and runs negentropy doctor.

Drop in one LLM key in .env.docker.local (gitignored) to enable chat:

OPENAI_API_KEY=sk-...        # or ANTHROPIC_API_KEY / GEMINI_API_KEY

Then open http://localhost:3192.

Service	URL
backend	http://localhost:3292 (+ /docs, /health)
ui (chat)	http://localhost:3192
wiki (knowledge base)	http://localhost:3092
perceives (content extraction)	http://localhost:2992

B. Native path (hot-reload, no Docker)

git clone https://github.com/ThreeFish-AI/negentropy.git
cd negentropy
./scripts/dev native     # delegates to scripts/cli.sh: deps + migrations + frontend build + all services

Requires a local pgvector Postgres. pg_cron is no longer needed — since migration 0042, scheduling runs in-process.

C. More

• First-run demo content: ./scripts/dev seed-demo
• Preflight self-check: ./scripts/dev doctor
• All subcommands: ./scripts/dev help
• Contributors: uv tool install pre-commit && pre-commit install
• Env setup, migrations, integrations, troubleshooting: Development Guide
• Zero-key local LLM: Local LLM (Ollama)
• Docker operations (production deploy): Docker Operations

---

🏛️ Architecture Overview

Design Philosophy | The system's namesake draws from Erwin Schrödinger's concept in What is Life?—life feeds on negative entropy (Negentropy)¹.

One Root, Five Wings

The NegentropyEngine refrains from executing atomic tasks directly; it exists solely for scheduling and dispatching. The five faculties operate purely in their element, while three pipelines encapsulate common multi-faculty collaboration patterns. The architecture rigidly adheres to Orthogonal Decomposition, ensuring decoupled responsibilities and strictly localized mutations.

Totem	Faculty	Agent Name	Combats	Core Responsibility	Exclusive Tools
👁️	The Eye · Perception	PerceptionFaculty	Information Overload	Wide-area scanning, noise filtering, multi-source cross-validation	search_knowledge_base, search_web
💎	The Soul · Internalization	InternalizationFaculty	Amnesia	Knowledge structuring, long-term memory governance, consistency maintenance	save_to_memory, update_knowledge_graph
🧠	The Mind · Contemplation	ContemplationFaculty	Superficiality	Second-order thinking, strategic planning, root cause analysis	analyze_context, create_plan
✋	The Hand · Action	ActionFaculty	All Talk	Precision execution, code generation, safe mutation	execute_code, read_file, write_file
🗣️	The Voice · Influence	InfluenceFaculty	Obscurity	Value delivery, format adaptation, persuasion and education	publish_content, send_notification

Dive into the complete architectural blueprint, pipeline orchestration mechanics, and design pattern registry in docs/framework.md.

Three-Tier Architecture

_{4 flows · 13 beats. Each beat lights one hop and dims the rest - so you see what a request actually touches, and what it never does.
Prefer no motion? The same diagram, still at 5120×2880: dark · light · vector}

Three tiers, 11 components, 11 relationships. Tier boundaries are contracts, not conventions: applications collaborate only over network protocols (AG-UI / HTTP / MCP) or build-time static artifacts - never by importing one another's source.

Tier	Components	Boundary rule
🖥️ Presentation	negentropy-ui · Next.js 16 · React 19 · Tailwind · :3192 negentropy-wiki · Next.js · pure static export	The UI reaches the engine over AG-UI only; the wiki holds no runtime link at all
⚙️ Engine	Backend API · ADK Web Server · FastAPI · :3292 NegentropyEngine · root agent (The Self), orchestration only Three Pipelines · each a SequentialAgent Five Faculties · Eye · Soul · Mind · Hand · Voice	The root executes no atomic work; it dispatches solely via transfer_to_agent
🏗️ Infrastructure	negentropy-perceives · MCP server, Web/PDF → Markdown · :2992 PostgreSQL 17 · pgvector · :5432 LiteLLM · 100+ providers MicroSandbox · OpenTelemetry · Langfuse	Reached only through faculty tools; no upper tier carries a driver-level dependency

Those 11 relationships resolve into four flows plus one cross-cut - the same decomposition the motion story walks:

1. Chat request (5 beats) - ui →AG-UI Protocol→ api → root →*transfer_to_agent*→ pipelines / faculties, terminating in PostgreSQL over SQL · asyncpg.
2. Knowledge ingestion (3 beats) - faculties →MCP→ negentropy-perceives turns Web and PDF sources into Markdown, persisted with vectors.
3. Static delivery (2 beats) - api ⇢publish · build-time bake⇢ wiki. Dashed on purpose: a published wiki stays readable with the engine offline.
4. Models and sandbox (3 beats) - root →LLM I/O→ LiteLLM; faculties →*execute_code*→ MicroSandbox. Neither sits on the request path.
5. Cross-cut - api ⇢OTLP traces⇢ OpenTelemetry · Langfuse, instrumenting all four flows while belonging to none.

Explore further

• 🖱️ Interactive diagram - architecture-diagram.html: pan / zoom / node search, relationship focus, light-dark toggle, a replayable guided story of 4 chapters and 13 beats, and 11 deep links jumping straight to the source file that substantiates each component. Download and open locally for the full interaction.
• 🎬 Motion story - negentropy-architecture-story.mp4: the same 29-second walkthrough at 1280×720 - sharper than the GIF above, which is capped at 720 px to stay under the repository's 1 MiB per-file limit.
• 📝 Diagram source - negentropy-architecture.mmd is the single editable source: archify rebuilds the interactive HTML from it, and the capture script derives every artifact above. It doubles as the diffable baseline.

Diagram text source - docs/assets/mermaid/core/negentropy-architecture.mmd: the single editable, diff-friendly baseline every artifact above is regenerated from. Edit it first, rebuild architecture-diagram.html with the archify skill (wholesale replacement - the capture script reads only this HTML), then run scripts/capture-arch-media.mjs to re-derive the artifacts. Never hand-edit the generated HTML - see doc-media-assets.md.

---

📚 Document Navigator

Document	Description
User Guide	End-user guide covering all features: chat, knowledge, memory, plugins, admin, and wiki
Development Guide	Environment setup, daily workflows, db migrations, integrations, troubleshooting
Docker Operations	Compose service topology, local one-click path, production deploy, ops runbook
Local LLM (Ollama)	Optional zero-key local LLM via Ollama (install, register, caveats)
Architecture Design	Deep dive into the One Root/Five Wings, pipeline choreography, design patterns, engine workings
Knowledge System	Detailed design and usage of the knowledge management module
Memory System	Memory lifecycle, forgetting curves, and governance mechanics
Knowledge Graph	Graph modeling and query implementation
QA Pipeline	Quality gates and release workflows
SSO Integration	Google OAuth authentication config
Engineering Changelog	Milestones and baseline mutation records
Agent-side Docs	Knowledge index: agent-side conventions, issue log, and media-asset governance

---

🤝 Community & Contributions

If you're holding onto an inspiration that pulls chaos back into order, or if you bump into any snags while navigating the system, please don't hesitate to share your wisdom:

1. Before hitting the keyboard, kindly take a detour through the Development Guide.
2. Sling your game-changing ideas into our Issues or directly submit a Pull Request packing some serious paradigm-shifting power.

Please hold "Entropy Reduction," "Context-Driven," and "Evidence-Based Engineering" as your core principles, ensuring every mutation aligns perfectly with Systemic Integrity.

---

[1] E. Schrödinger, "What is Life? The Physical Aspect of the Living Cell," Cambridge University Press, 1944.

---

_{Built with 🧠, ❤️, and an absurd amount of coffee by ThreeFish-AI · Released under the Apache License 2.0.}