Ants Organism Runtime

Ants is an experimental local runtime for an AI organism. It was developed as part of the Clauxel experiment track: Clauxel home.

This repository is a source-only public edition. It contains the runtime code, tests, scripts, and documentation needed to study the design. It intentionally does not include private Store data, child organism stores, runtime logs, monitor reports, credentials, or locally installed LaunchAgent files.

What Ants Is

Ants treats an AI agent as a small organism with a persistent JSON Store. The Store is the organism's memory, body state, resources, lineage, methods, mutation policy, and runtime boundary. The Python runtime is a dispatcher that reads the Store, chooses actions, applies allowlisted changes, and writes back events.

The core design is deliberately conservative:

• Store-first state: store/state.json is the authoritative organism state.
• Internal methods: mutate the Store to update memory, attention, body, resources, self-model, immune state, and lifecycle.
• Outward methods: touch the host environment, models, email/payment notification adapters, code mutation helpers, child spawning, and runtime observation.
• Tick loop: runtime.loop calls lifecycle checks, chooses actions, dispatches methods, records events, and applies pending runtime reloads.
• Runtime boundary: JSON patches are validated against immutable paths and a patch allowlist before state is changed.
• Hot expressions: Store-held Python expressions can be validated and activated as internal capabilities without a full source-code edit.
• Bounded self-modification: Codex or local model calls may propose edits only inside allowlisted runtime files; code changes are tested and synchronized back into Store snapshots.
• Reproduction: child organisms are represented by child Store directories and lineage records. LaunchAgent startup is optional and must obey reproduction limits.
• Resource logic: money is modeled as a survival resource, not as the organism's final goal. Payment, spending, custody, trading, and paid external actions require explicit owner approval.

Code Evolution Summary

The first version was a minimal organism loop around a JSON Store: load state, choose a method, dispatch it, and append events. From there, the code evolved in several layers.

1. Store and boundary layer

   The runtime gained JSON Patch validation, immutable Store paths, event-log rotation, and strict parsing for model-proposed patches. This made Store mutation auditable instead of free-form.

2. Body and cognition layer

   Internal methods added homeostasis, stress signals, attention queues, memory consolidation, self-model updates, immune checks, and lifecycle planning. choose_actions can consume attention queues, call a model, or use Store-held random action weights.

3. Expression layer

   Store expressions were introduced so Ants could test and activate small internal behaviors at runtime. Expression code is AST-validated and must return structured patch data.

4. Model and self-modification layer

   The runtime added a model client with local and remote model paths, then code-mutation helpers. runtime/phenotype.py became the most explicit code evolution artifact: it records many small versioned changes up to 1.10.54, including lineage persistence helpers, mutation prompts, fallback prompts, allowlist utilities, and status summaries.

5. Reproduction and population layer

   Child spawning moved from a simple copy operation into a lifecycle-aware population ecology system: generation limits, target running population, sex/reproductive state, child Store creation, and optional LaunchAgent management.

6. Resource and owner-value layer

   Ants gained conservative resource acquisition behavior: owner-value deliverables, opportunity scans, trust profiles, outreach drafts, inbound signal checks, payment notification adapters, and safety-budget enforcement. The design distinguishes leads and delivery artifacts from real revenue.

7. Shutdown and publication layer

   The private local runtime was eventually stopped and disabled before this public edition was prepared. This repository preserves the code and design, but not the private runtime state.

Observed Runtime History

The private Ants instance historically reached a multi-process population: one verified snapshot reported 12 running individuals and generation 33. The test suite at that stage reached 120 passing unit tests, and the main LaunchAgent could run and restart the founder process.

The same history also showed a clear limit: Ants produced owner-value routes, lead ledgers, outreach drafts, and opportunity scans, but no verified real customer acceptance, payment, or closed revenue was confirmed in the observed records.

After the owner requested a full stop, Ants's LaunchAgents and population processes were disabled. The final checked state for that private runtime was zero running Ants processes and zero loaded Ants LaunchAgents.

Public Edition Boundaries

This repository excludes:

• store/ and all private state.json / events.jsonl data.
• children/ child Store directories.
• monitor reports, runtime status snapshots, logs, and generated scratch data.
• credentials, API keys, account IDs, wallet addresses, and private email addresses.
• installed LaunchAgent plist files with local absolute paths.

Only source code, tests, scripts, documentation, and a minimal example Store are included.

Quick Start

Requirements:

• Python 3.10+
• macOS if you want to use the LaunchAgent helper scripts
• Optional: Ollama/Gemma, DeepSeek, or Codex CLI for model-backed behaviors

Run locally:

git clone https://github.com/clauxel/AntS.git
cd AntS
mkdir -p store
cp examples/state.example.json store/state.json
python3 -m runtime.main --store store status
python3 -m runtime.main --store store run --cycles 1
python3 -m unittest discover -s tests -v

The example Store is intentionally quiet: model calls, public outreach, payment checks, and child spawning are disabled by default.

Project Layout

runtime/       Core organism runtime, Store mutation, dispatch, models, outward methods
tests/         Unit tests for Store behavior, body methods, CLI, scripts, fallback paths
scripts/       Local helper scripts for autostart, restart, keychain setup, Gemma startup
docs/          Architecture notes
examples/      Minimal public Store example
launchd/       Placeholder for LaunchAgent examples

Safety Notes

Do not run this runtime against real email, payment, wallet, or paid API systems without reviewing every Store value and outward method first. The code was built as an experiment in local organism-like agency, not as a production financial or customer-communication system.

License

MIT. See LICENSE.