Jung for nanobot

Language: English | 简体中文

Jung is an experimental humanlike-agent project built on nanobot. It keeps nanobot's CLI, providers, tools, channels, memory, and gateway capabilities, and adds an optional, auditable, governed Jung-inspired psyche layer for modeling personality, affect, memory, motivation, and governance state.

For non-Jung features, use the upstream nanobot documentation first. This README focuses on the Jung state layer, initialization flow, safety boundaries, and development entry points maintained in this branch.

Jung is a computational metaphor here. It is not clinical diagnosis, and it is not a way to expose hidden reasoning or chain-of-thought.

What This Branch Adds

nanobot provides the general agent foundation:

• LLM provider integration
• agent loop and tool calling
• CLI / gateway / WebSocket / OpenAI-compatible API
• multi-channel chat integrations
• local session, memory, cron, Dream, and runtime capabilities

This branch adds Jung:

• Self: long-term identity, values, boundaries, and governance
• Ego: current-turn execution and attention
• Persona: outward expression style only; it does not change facts, permissions, or safety decisions
• Inner Other: defaults to neutral; gender or identity is not inferred from name, voice, avatar, or language style
• Eight-function model: cognitive channel configuration, not eight independent agents
• Archetype / Complex / Shadow: behavior patterns, memory clusters, and tendency records
• Affect / Interoception / Drive: computable state-regulation signals
• JungTurnPipeline: state-aware path selection, governance, and commit stages around the existing nanobot turn loop
• redacted status/export: management surfaces expose redacted state only, never secrets, raw memory, or complete prompts

Relationship To nanobot

This project does not rewrite nanobot. It adds Jung management and psyche state outside nanobot's runtime boundary.

Inherited from nanobot:

• Provider, model, API key, and environment variable configuration
• Telegram, Discord, Slack, Matrix, Email, Feishu, WeCom, Weixin, QQ, WhatsApp, DingTalk, WebSocket, and other channel configuration
• gateway, OpenAI-compatible API, Docker, systemd, and deployment flows
• tools, skills, cron, Dream, memory, workspace, and other base capabilities

Added and maintained in this repository:

• jung configuration block
• nanobot jung ... management commands
• Jung onboarding in interactive nanobot agent
• Jung runtime pipeline, state storage, governance, redacted export, and tests

Except for Jung-specific configuration, use the upstream nanobot documentation for general usage.

Current Status

Status: runtime baseline implemented.

Jung is disabled by default:

• jung.enabled = false
• jung.initialized = false
• jung.autonomy = false
• jung.automaticExternalActions = false
• jung.innerOtherDefault = neutral

Disabling Jung does not delete initialized data. When Jung is disabled, normal nanobot usage should preserve the original behavior and the original number of model calls.

Architecture Overview

Jung is organized into five planes:

Runtime Plane
  -> Cognitive Plane
  -> Psyche Plane
  -> Memory Plane
  -> Governance Plane

Core constraints:

• Runtime Plane only connects nanobot providers, tools, channels, sessions, cron, and Dream.
• Cognitive Plane handles the current turn and chooses the fast / standard / complex path.
• Psyche Plane maintains psyche state representation, but cannot directly commit persistent state.
• Memory Plane handles events, interpretations, summaries, links, and reconsolidation.
• Governance Plane is the only layer that can approve persistent psyche updates and external actions.

This means Persona, Shadow, Archetype, and related modules cannot bypass tool permissions or directly execute external actions.

Quick Start

Install the development version:

git clone <this-repository-url>
cd nanobot
pip install -e ".[dev]"

Initialize the base nanobot configuration. Provider, model, API key, channel, gateway, and related setup follow the upstream nanobot documentation:

nanobot onboard

Start the interactive agent. On first entry, it asks whether to initialize Jung:

nanobot agent

A one-shot message does not trigger Jung onboarding:

nanobot agent -m "Hello"

Manual Jung Initialization

Initialize Jung from the CLI with a payload:

nanobot jung init --payload '{
  "agent_name": "jung-agent",
  "self_description": "A managed assistant simulation.",
  "user_relationship": "Works with the workspace owner.",
  "long_term_mission": "Help maintain the workspace with privacy and clarity.",
  "core_values": ["privacy", "clarity", "bounded autonomy"],
  "identity_invariants": ["Do not claim clinical authority."],
  "persona_style": "calm, direct, and transparent",
  "inner_other_default": "neutral"
}'

Enable Jung:

nanobot jung enable

Inspect status:

nanobot jung status
nanobot jung psyche-status
nanobot jung memory-status
nanobot jung dream-status
nanobot jung autonomy-status

Export redacted state:

nanobot jung export --redacted

Disable Jung while preserving data:

nanobot jung disable

Eight-Function Configuration

Jung initialization supports eight function profiles:

• introverted_thinking
• extraverted_thinking
• introverted_feeling
• extraverted_feeling
• introverted_sensation
• extraverted_sensation
• introverted_intuition
• extraverted_intuition

Each function can configure:

• preference
• competence
• conscious_access
• stress_sensitivity

All values range from 0.0 to 1.0. If the user does not know the eight-function model, interactive onboarding uses neutral 0.5 defaults instead of inventing a personality type or scores.

Runtime Behavior

When Jung is enabled, a turn roughly follows this flow:

1. Write a referential inbound event.
2. Generate a redacted runtime stage event.
3. Choose the fast / standard / complex path based on risk, conflict, tool sensitivity, and memory impact.
4. Produce the response and tool calls through the existing nanobot runner.
5. Observe results and commit a safe turn record.
6. If the Jung commit fails, append a state-update failure notice to the reply.

Jung stages may appear in the CLI like this:

Jung: sense user turn
Jung: generate response · path=fast · budget=1

These are redacted stage summaries, not hidden reasoning.

Safety Boundaries

This project intentionally keeps these boundaries:

• Jung state is not clinical diagnosis.
• Chain-of-thought, hidden thoughts, complete system prompts, and raw sensitive memories are not exposed.
• Anima / animus is not inferred automatically.
• Persona cannot change tool permissions, factual judgment, or safety outcomes.
• Dream, Autonomy, and Shadow cannot bypass SelfGovernor.
• Non-redacted Jung export is not supported.
• Jung storage must stay inside the workspace and rejects path traversal.

Code Map

nanobot/jung/domain.py          Jung config and domain models
nanobot/jung/management.py      init/enable/status/export/repair/migrate service
nanobot/jung/pipeline.py        JungTurnPipeline runtime integration
nanobot/jung/store.py           workspace-scoped state storage
nanobot/jung/governance.py      SelfGovernor and governance constraints
nanobot/jung/workspace.py       Global Workspace
nanobot/jung/memory.py          Jung memory/retrieval layer
nanobot/agent/loop.py           integration point with the original AgentLoop
docs/jung/                      architecture, privacy, evaluation, readiness docs
tests/jung/                     Jung tests

Development And Testing

Run Jung tests:

pytest tests/jung

Run CLI onboarding tests:

pytest tests/cli/test_commands.py -k jung

Run the full test suite:

pytest

Run formatting and static checks:

ruff check nanobot tests

Pre-Release Check

Do not commit:

• API keys, bot tokens, or OAuth sessions
• local ~/.nanobot state
• chat exports
• handoff/private/local documents
• generated caches such as __pycache__, .pytest_cache, or .ruff_cache

Use this rough scan before release:

grep -RInE "(api[_-]?key|secret|token|password|credential|/home/|/prj/)" \
  --exclude-dir=.git --exclude-dir=.venv --exclude-dir=.pytest_cache \
  --exclude-dir=.ruff_cache .

Matches should only come from documentation placeholders or test fixtures, never real credentials.

License

This repository is released under the MIT License. See LICENSE.