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.

graph TB
    Root["🔮 NegentropyEngine<br/>(The Self · Scheduling Core)"]

    Root -->|"transfer_to_agent"| P["👁️ The Eye · Perception Faculty"]
    Root -->|"transfer_to_agent"| I["💎 The Soul · Internalization Faculty"]
    Root -->|"transfer_to_agent"| C["🧠 The Mind · Contemplation Faculty"]
    Root -->|"transfer_to_agent"| A["✋ The Hand · Action Faculty"]
    Root -->|"transfer_to_agent"| Inf["🗣️ The Voice · Influence Faculty"]

    P -->|Combats| O["Information Overload<br/>Noise Drowning Signal"]
    I -->|Combats| F["Amnesia<br/>Knowledge Fragmentation"]
    C -->|Combats| S["Superficiality<br/>Surface-Level Responses"]
    A -->|Combats| E["All Talk<br/>Cognitive-Action Disconnect"]
    Inf -->|Combats| Obs["Obscurity<br/>Value Degradation"]

Loading

---

✨ 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
./dev            # = setup + build & start the full stack + health self-check

./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
./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: ./dev seed-demo
• Preflight self-check: ./dev doctor
• All subcommands: ./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

Note: apps/cognizes is a separate project; ./dev and docker compose do not start it.

---

🏛️ 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

graph TB
    subgraph Presentation["🖥️ Presentation Layer"]
        UI["negentropy-ui<br/><i>Next.js 16 · React 19 · Tailwind</i>"]
        Wiki["negentropy-wiki<br/><i>Next.js</i>"]
    end

    subgraph Engine["⚙️ Engine Layer"]
        Root["🔮 NegentropyEngine<br/>Root Agent (The Self)"]
        Faculties["Five Faculties<br/>👁️ Perception <br> 💎 Internalization <br> 🧠 Contemplation <br> ✋ Action <br> 🗣️ Influence"]
        Pipelines["Three Pipelines<br/>Knowledge Acquisition <br> Problem Solving <br> Value Delivery"]
    end

    subgraph Infra["🏗️ Infrastructure Layer"]
        DB[("PostgreSQL 16+<br/>pgvector")]
        LLM["LiteLLM<br/>100+ LLMs Unified API"]
        OTel["OpenTelemetry · Langfuse"]
        Sandbox["MCP · MicroSandbox"]
    end

    UI -->|"AG-UI Protocol"| Root
    Wiki -->|"HTTP/JSON"| Root
    Root --> Faculties
    Root --> Pipelines
    Pipelines --> Faculties
    Faculties --> DB
    Faculties --> Sandbox
    Root --> LLM
    Root -.-> OTel

    classDef pres fill:#60A5FA,stroke:#1E3A8A,color:#000
    classDef eng fill:#F59E0B,stroke:#92400E,color:#000
    classDef infra fill:#10B981,stroke:#065F46,color:#FFF

    class UI,Wiki pres
    class Root,Faculties,Pipelines eng
    class DB,LLM,OTel,Sandbox infra

Loading

---

📚 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
AI Collaboration Protocol	Agent cooperation guidelines and engineering codebase

---

🤝 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.

---

Apache License 2.0, © 2026 ThreeFish-AI