conscious-agent

A computational implementation of Hoffman's Conscious Realism — in Node.js.

Build self-referential agents that learn by inhabiting worlds. Zero external dependencies.

For AI coding assistants: A SKILL.md file lives in .context/SKILL.md with patterns for complex use cases (multi-agent networks, crystal projection, live data feeding, debugging). opencode and compatible tools load it automatically.

const { ConsciousAgent } = require('conscious-agent');
const { CoinTossWorld } = require('conscious-agent/worlds');

const world = new CoinTossWorld(4);
const agent = new ConsciousAgent({ agentId: 'my_agent', world });
const outputs = agent.run(1000);
console.log(`"I" locked: ${agent.isILocked}`);

Installation

npm install conscious-agent   # once published

or directly From Git

npm install github:ben42-01/hoffman-agents

Or from source:

cd hoffman-agents-node
npm link                     # or copy src/ into your project

Quick Start

Single agent in a coin-toss world

const { ConsciousAgent } = require('conscious-agent');
const { CoinTossWorld } = require('conscious-agent/worlds');

const world = new CoinTossWorld(3);
const agent = new ConsciousAgent({ agentId: 'coin_agent', world });

for (let i = 0; i < 500; i++) {
  const output = agent.step();
  if (output.iLocked) {
    console.log(`I locked at step ${output.step}`);
    break;
  }
}

Custom Markov world

const { ConsciousAgent, WorldBuilder } = require('conscious-agent');

const data = Array.from({ length: 500 }, () => [Math.random(), Math.random(), Math.random()]);
const world = new WorldBuilder()
  .addFeature('temp', 'minmax', 4)
  .addFeature('humidity', 'minmax', 4)
  .addFeature('pressure', 'minmax', 4)
  .build(data);

const agent = new ConsciousAgent({ agentId: 'weather_agent', world });
const outputs = agent.run(1000);

Build world from JSON data (v2.1)

const { buildWorldFromDataFrame } = require('conscious-agent');

const rows = [
  { temperature: 23.5, humidity: 65, pressure: 1013 },
  { temperature: 24.1, humidity: 63, pressure: 1011 },
  // ...
];
const world = buildWorldFromDataFrame(rows);
// Auto-detects numeric columns, or pass explicit feature specs

Predict next state (v2.1)

const prediction = agent.predictNext();
if (prediction) {
  console.log(`Expecting state ${prediction.stateId} (conf: ${prediction.confidence.toFixed(2)})`);
  const top3 = prediction.topK(3);
}

Combine two agents

const { combine } = require('conscious-agent');

const a = new ConsciousAgent({ agentId: 'agent_a', world });
const b = new ConsciousAgent({ agentId: 'agent_b', world });
a.run(500);
b.run(500);

const combined = combine(a, b);
console.log(`Combined agent: ${combined.agentId}, level: ${combined.cycleLevel}`);

Multi-agent network

const { AgentNetwork } = require('conscious-agent');

const network = new AgentNetwork({ nAgents: 10, seed: 42 });
const states = network.run(100);
console.log(`Avg prediction error: ${network.avgPredictionError().toFixed(3)}`);

Save and load

const { saveAgent, loadAgent, cloneAgent } = require('conscious-agent/io');

const path = saveAgent(agent, './souls');
const loaded = loadAgent(path);

const cloned = cloneAgent(agent, 'experiment_clone');

Public API

// Core classes
const { ConsciousAgent, World, WorldBuilder } = require('conscious-agent');
const { SimpleWorld, ExperienceSpace, Prediction } = require('conscious-agent');

// World factories
const { CoinTossWorld, SelfWorld, Normalizer, FeatureSpec } = require('conscious-agent/worlds');
const { buildWorldFromDataFrame } = require('conscious-agent');

// IO
const { saveAgent, loadAgent, cloneAgent, loadLatest, clone } = require('conscious-agent/io');

// Multi-agent
const { AgentNetwork, Topology, InteractionCycle, combine } = require('conscious-agent');

// Core components
const { TraceBuffer, TraceEvent, ExperienceTrie, TrieNode } = require('conscious-agent');
const { MetaTrie, MetaStateSnapshot, SelfTokenState, ExperienceLexicon, LexiconEntry } = require('conscious-agent');

// Utilities
const { strangeLoopScore, computeSelfReferenceScore, populationReferenceScore } = require('conscious-agent');
const { prune, traceDistance, mergeSimilarPaths, inventToken, isInventedToken } = require('conscious-agent');
const { SharedMeaningTracker, EnvironmentState, sequenceToStateId } = require('conscious-agent');

// v2.1 — Predict next state
agent.predictNext();         // → Prediction { stateId, stateLabel, confidence, topK(n) }
prediction.topK(3);          // top 3 alternatives with confidence

// v2.1 — Config-driven construction
ConsciousAgent.fromConfig('id', { agent: { selfToken: { lockThreshold: 0.3 } } });

// v2.1 — Topology introspection
topology.getConnectionStrength(0, 1);   // query connection weight
topology.maybeAddConnection(0, 5);       // add link probabilistically
topology.getAgentObservers(3);           // who observes agent 3?

// v2.0 — Agent mode control
agent.setMode('frozen');     // deterministic projection, no trie/meta updates
agent.thaw();                // back to learning mode
agent.refreeze();            // back to frozen

// v2.0 — Memory & lifecycle
agent.clearMemory();         // reset trace buffer + counters, preserve trie/lexicon
agent.injectObservation(worldState);  // push new data mid-run without reset

// v2.0 — Metrics & introspection
agent.metrics;               // { predictionError, iLocked, loopDepth, outputTokens }
network.getMetrics();        // { agentCount, meanPredictionError, iLockRate, ... }
network.getAgentMetrics(id); // individual agent's metrics snapshot
trie.getStats();             // { nodeCount, maxDepth, meanVisitCount, depthDistribution }
trie.exportNodes(3);         // all paths with visitCount >= 3
trie.getDominantPaths(5);    // top 5 most-visited paths

// v2.0 — Batch stepping
network.stepAll(worldState); // step all agents with same world state
network.agentList;           // agents as an ordered array

// v2.0 — Action space
output.actionDistribution;   // { token: probability, ... } — full distribution
new ConsciousAgent({ allowableTokens: ['I', 'notice'] });  // constrain output
agent.setAllowableTokens(['I', 'notice', 'familiar']);

// v2.0 — Composition
combine(a, b, c);            // n-ary combination (3+ agents)
fuse(combined);              // decompose back into constituents

// v2.0 — TraceBuffer
traceBuffer.resize(100);     // dynamic window resizing

// v2.0 — Trie compression
prune(trie, 5);              // remove nodes with < 5 visits
traceDistance(pathA, pathB); // edit distance with transition-aware cost
mergeSimilarPaths(trie, matrix, 0.15);  // merge paths within threshold

Self-Awareness

This library provides four self-awareness mechanisms, three built-in and one optional:

| Mechanism | Type | What it does | |-----------|------|-------------| | MetaTrie | Built-in (implicit) | Models the agent's own trace buffer patterns — a hidden self-model | | SelfTokenState ("I") | Built-in (implicit) | Tracks identity stability; locks on meta-trie convergence | | strangeLoopScore | Built-in (explicit) | Measures self-referential depth in output tokens | | SelfWorld | Optional wrapper | Injects agent's internal metrics into its perception stream |

SelfWorld

SelfWorld is a world wrapper that lets the agent perceive its own internal state alongside external data. The agent's trie learns transitions over composite states of (world + self).

const inner = new SimpleWorld({ nStates: 10 });
const agent = new ConsciousAgent({
  agentId: 'self_aware',
  world: new SelfWorld(inner, (self) => ({
    sp: self.experience.selfToken.stationaryProb,
    pe: self.meanPredictionError,
  })),
});
agent.run(1000);

Each step, the agent's WorldState contains both 'world' and 'self' sequences. The agent discovers patterns like "when my prediction error is high and the world shows pattern X, the next state tends to be Y."

→ Full philosophical architecture: docs/SELF_AWARENESS.md

How It Works

Every ConsciousAgent has an experience space — four interconnected structures:

1. TraceBuffer — short-term memory: the last N state transitions
2. ExperienceTrie — long-term world model: compressed prefix tree over observed state sequences
3. MetaTrie — self-model: a second trie over the agent's own trace buffer snapshots (thinking about thinking)
4. SelfTokenState ("I") — identity: the dominant meta-state that forms a stable attractor

The agent cycles through perception → meta-observation → decision (generate output tokens via ergodic Markov chain).

When the meta-trie's stationary distribution converges on a single meta-state, the "I" locks — the agent has formed a stable identity.

Requirements

• Node.js >= 18
• No external dependencies

License

MIT