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"]

✨ 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

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.

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)¹.

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