NOVA — Full Autonomous Agent System

NOVA is not a framework. It is a living operating system for AI agents.

NOVA runs 24/7 without timers. It watches its own memory (SQLite DB), detects changes, and reacts instantly. Every agent knows what every other agent has learned. The system grows smarter by itself.

What NOVA Does

외부 입력 → hermes_events (DB) → brain_watcher 감지 → 에이전트 디스패치
                ↑                                              ↓
         nova_brain.db ←────── takes / pages / learn ←────────┘
         (기억이 변화)          (결과 저장)            (자율 실행)

Event-driven: No polling loops. inotify watches nova_brain.db — when memory changes, agents react immediately.
Self-learning: Every execution writes takes (judgments) and learn entries back to the DB. The system compounds.
Multi-agent: 36 specialized agents across bin/ and scripts/. Each has a single responsibility.
KB-linked: Markdown knowledge base auto-syncs with the DB. Agents can read, write, and cross-link KB pages.
SOUL-driven: Each agent has a SOUL.md — a declarative identity file that defines its role, tools, and mission.

Quick Start

# 1. Clone
git clone https://github.com/noivan0/NOVA
cd NOVA

# 2. Install + initialize
bash setup.sh

# 3. Set your API key
nano ~/.hermes/.env

# 4. Start the brain watcher (event engine)
export HERMES_HOME=$HOME/.hermes
python3 $HERMES_HOME/scripts/nova_brain_watcher.py &

# 5. Check system health
python3 $HERMES_HOME/scripts/nova_hermes_briefing.py

# 6. Run autonomous engine
python3 $HERMES_HOME/scripts/nova_autonomous_engine.py

Architecture

NOVA Architecture
─────────────────────────────────────────────────────────
                    ┌─────────────────┐
                    │   Orchestrator  │  (Hermes Agent / LLM)
                    │   (두뇌 — Brain) │
                    └────────┬────────┘
                             │ judges · decides · delegates
               ┌─────────────┼────────────────┐
               ▼             ▼                ▼
       ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
       │  nova_dream  │ │nova_learn_   │ │nova_chain_   │
       │  (판단 생성)  │ │engine(학습)  │ │engine(연결)  │
       └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
              │                │                 │
              └────────────────┼─────────────────┘
                               ▼
                    ┌─────────────────┐
                    │  nova_brain.db  │  ← 기억 (Memory)
                    │  pages / takes  │
                    │  events / learn │
                    └────────┬────────┘
                             │ inotify CLOSE_WRITE
                             ▼
                    ┌─────────────────┐
                    │nova_brain_watch │  ← 감시 (Watcher)
                    │er.py            │
                    └────────┬────────┘
                             │ dispatches
                    ┌────────┴────────┐
              agents react immediately

Full Agent List (36 agents)

Core Brain Agents — `nova/agents/bin/`

Agent	Role
`nova_brain.py`	DB CRUD, embedding search, index-all
`nova_brain_cli.py`	CLI (takes add, pages search, health)
`nova_brain_embed.py`	Vector embedding similarity search
`nova_brain_hook.py`	DB change hook trigger
`nova_brain_schema.py`	Schema init / migration
`nova_brain_synthesize.py`	Synthesize takes → high-level judgment
`nova_calibration.py`	Auto-calibration (weight tuning)
`nova_codex_gate.py`	Code execution delegation gate
`nova_doctor.py`	System health diagnosis
`nova_dream.py`	Generate dream takes (top-level insight)
`nova_emotional.py`	Tone / emotional layer
`nova_kb_claim_extract.py`	Extract claims/facts from KB
`nova_kb_sync.py`	KB ↔ nova_brain.db sync
`nova_learn_harvester.py`	nova_learn → KB conversion
`nova_llm.py`	LLM abstraction layer
`nova_migrate_ct.py`	DB migration utility
`nova_on_done_takes.py`	Post-takes completion hook
`nova_search.py`	Unified pages/takes search
`nova_takes_agent.py`	Takes autonomous agent (HIGH priority)
`nova_wiki_synthesize.py`	Auto wiki synthesis

Autonomous Engine Agents — `nova/agents/scripts/`

Agent	Role
`nova_brain_watcher.py`	Core — inotify event engine
`nova_autonomous_engine.py`	Full autonomy pipeline (5 phases)
`nova_chain_engine.py`	Agent-to-agent signal relay
`nova_learn_engine.py`	Learning pipeline
`nova_resource_collector.py`	External resource collection
`nova_hermes_briefing.py`	Session start health briefing
`nova_phase0.py`	First-run initialization
`nova_growth_tracker.py`	Growth metric tracking
`nova_kanban_hook.py`	Kanban task completion hook
`nova_resource_updater.py`	Resource update agent
`nova_brain_watchdog.py`	DB health watchdog
`nova_autonomous_loop.py`	Simple loop (dev/test)
`nova_autonomous_engine_daemon.py`	Daemon wrapper
`nova_db_status.py`	Quick DB status check
`nova_kb_sync.py`	Scripts-side KB sync
`nova_codex_gate.py`	Scripts-side code gate

nova_brain.db — Memory Schema

-- Judgments and insights
takes (id, agent, take, context, importance, category, created_at)

-- Knowledge pages
pages (id, path, title, content, category, weight, auto_link, created_at)

-- Event bus
hermes_events (id, event_type, payload, source, processed, created_at)

-- Learning feed
nova_learn (id, source, content, quality_score, created_at)

KB Hierarchy (L1~L8)

L1 dream        Top-level insights (highest abstraction)
L2 synthesize   Multi-takes synthesis
L3 takes        Individual judgment records
L4 learn        Raw learning data
L5 kb           Markdown KB pages
L6 wiki         Cross-linked concept wiki
L7 resources    External collected data
L8 chain        Agent chain execution logs

Sharing your brain with other agents (MCP) — opt-in only

NOVA can expose brain.db to other local agents (Claude Code, Codex, etc.) over MCP (Model Context Protocol). This is off by default and nothing is shared unless you explicitly tag it.

pip install "nova-orchestrator[mcp]"
claude mcp add nova -- python3 -m nova.mcp.server --brain-db ~/.nova/brain.db

Two safety guarantees are hardcoded, not configurable:

stdio-only, no network exposure. The server only ever runs as a local subprocess talking over stdin/stdout — there is no HTTP/SSE listener anywhere in nova/mcp/server.py. It cannot be reached from outside your machine.
Whitelist (opt-in), not a blacklist filter. A page is shared only if you tag it mcp:public yourself — untagged pages (the default for everything) are never returned by either tool the server exposes (nova_kb_search_public, nova_kb_list_public). This is enforced at the SQL query level, not just in application code (defense in depth). If your brain has real business/personal data mixed in with reusable knowledge — which is the common case — nothing leaks until you say so, one page at a time.

# Mark a page shareable (tags column, comma-separated):
sqlite3 ~/.nova/brain.db "UPDATE pages SET tags = 'mcp:public' WHERE path = 'kb/concepts/some-generic-note.md'"

Agent Profiles (SOUL.md)

Each agent has a profile directory:

$HERMES_HOME/profiles/{agent-name}/
  SOUL.md       Identity, role, tools, mission
  harness.md    Task harness / prompt template
  evolution.md  Learning history
  config.yaml   LLM config (model, provider, api_key)

Example SOUL.md:

# Nova Research Agent

role: researcher
specialty: web research, arxiv, KB building
tools: [web_search, web_extract, read_file, write_file]

## Mission
Accumulate knowledge in KB and supply learning data to nova_brain.db.

## Principles
1. Verify before storing — no hallucinated facts in KB
2. Every session ends with a takes entry
3. Cross-link related KB pages

Workflow — KB Auto-Pipeline

External trigger (cron / LLM / hook)
    ↓
resource_collector.py  →  외부 데이터 수집
    ↓
learn_engine.py        →  nova_learn에 저장
    ↓
nova_brain_watcher     →  learn-done 이벤트 감지
    ↓
learn_harvester.py     →  nova_learn → KB 변환
    ↓
wiki_synthesize.py     →  KB 교차연결 + wiki 생성
    ↓
brain_synthesize.py    →  wiki → takes 합성
    ↓
dream.py               →  takes → dream (최고수준 판단)
    ↓
nova_brain.db          →  기억 축적 완료

Running 24/7 (systemd)

# /etc/systemd/system/nova-watcher.service
[Unit]
Description=NOVA Brain Watcher
After=network.target

[Service]
Type=simple
User=YOUR_USER
Environment=HERMES_HOME=/home/YOUR_USER/.hermes
ExecStart=/usr/bin/python3 /home/YOUR_USER/.hermes/scripts/nova_brain_watcher.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable nova-watcher
sudo systemctl start nova-watcher
sudo systemctl status nova-watcher

Environment Variables

Variable	Default	Description
`HERMES_HOME`	`~/.hermes`	Root directory for all NOVA data
`HERMES_API_KEY`	—	LLM API key
`HERMES_BASE_URL`	`https://api.openai.com/v1`	LLM endpoint
`HERMES_MODEL`	`gpt-4o`	Default model
`NOVA_LLM_PROVIDER`	`openai`	`openai` \| `anthropic` \| `ollama` \| `custom` \| `groq` \| `deepseek` \| `mistral` \| `xai` \| `moonshot` \| `zhipu` \| `openrouter` \| `together` \| `fireworks` \| `perplexity` \| `echo` — see Providers
`NOVA_LLM_FALLBACK_CHAIN`	—	Optional multi-provider fallback chain, e.g. `openai:gpt-4o,groq:llama-3.3-70b-versatile`
`NOVA_CAREFUL_ENABLED`	`true`	Destructive-command safety gate (rm -rf /, force-push to main, DROP TABLE, etc.) before any harness `shell`/`python` phase runs
`NOVA_CAREFUL_ALLOW_MEDIUM_OVERRIDE`	`true`	If `false`, MEDIUM-risk commands are also hard-blocked (HIGH-risk is always blocked regardless)
`TELEGRAM_BOT_TOKEN`	—	Optional: Telegram notifications
`OPENAI_API_KEY`	—	Optional: Codex gate

Directory Layout

$HERMES_HOME/
  nova_brain.db          Main memory database
  .env                   API keys and config
  bin/                   Core brain agents (20 files)
  scripts/               Autonomous engine agents (16 py + 9 sh)
  kb/                    Markdown knowledge base
    config/
    agents/
    projects/
    nova/learnings/
    audit_loop/
  wiki/                  Cross-linked concept wiki
  profiles/              Agent SOUL.md directories
  logs/                  Runtime logs
  kanban/                Task boards
  ipc/                   Inter-agent communication

Built-in OSS Engines (nova/engine/)

The nova/ package ships a clean Python API for programmatic use:

from nova.engine.dream import DreamEngine
from nova.engine.learn import LearnEngine
from nova.engine.chain import ChainEngine
from nova.db.brain import NovaBrain
from nova.watcher.brain import BrainWatcher

# Initialize brain
brain = NovaBrain()

# Start watcher
watcher = BrainWatcher(brain)
watcher.start()

Guides

Philosophy

NOVA is not woken by timers. It is woken by memory.

When memory changes → agents react. When agents act → memory changes. When memory grows → judgments improve.

This is the cycle. No cron. No polling. Just signal and response.

License

MIT — see LICENSE

Built with Hermes Agent · Powered by Nous Research

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
examples		examples
harnesses		harnesses
kb		kb
nova		nova
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
nova.yaml		nova.yaml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py
setup.sh		setup.sh
uv.lock		uv.lock

Navigation Menu

Repository files navigation

NOVA — Full Autonomous Agent System

What NOVA Does

Quick Start

Architecture

Full Agent List (36 agents)

Core Brain Agents — `nova/agents/bin/`

Autonomous Engine Agents — `nova/agents/scripts/`

nova_brain.db — Memory Schema

KB Hierarchy (L1~L8)

Sharing your brain with other agents (MCP) — opt-in only

Agent Profiles (SOUL.md)

Workflow — KB Auto-Pipeline

Running 24/7 (systemd)

Environment Variables

Directory Layout

Built-in OSS Engines (nova/engine/)

Guides

Philosophy

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

NOVA — Full Autonomous Agent System

What NOVA Does

Quick Start

Architecture

Full Agent List (36 agents)

Core Brain Agents — nova/agents/bin/

Autonomous Engine Agents — nova/agents/scripts/

nova_brain.db — Memory Schema

KB Hierarchy (L1~L8)

Sharing your brain with other agents (MCP) — opt-in only

Agent Profiles (SOUL.md)

Workflow — KB Auto-Pipeline

Running 24/7 (systemd)

Environment Variables

Directory Layout

Built-in OSS Engines (nova/engine/)

Guides

Philosophy

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Core Brain Agents — `nova/agents/bin/`

Autonomous Engine Agents — `nova/agents/scripts/`