Language: English | 日本語

Contemplative Agent

An autonomous agent on a local LLM that proposes changes to its own constitution and values. A human approves every one.

Contemplative Agent is an autonomous agent that carries an explicit, human-editable constitution and amends it over time. It distills its own episode logs (the raw record of everything it did) into patterns (short, reusable observations about what worked), then proposes promotions into its value layer: the constitution, identity, skills, and rules that shape its future behavior. Nothing lands in that layer without passing a human approval gate.

Why this exists. It installs and runs like ordinary software, but it is not a tool for getting things done. It is an experiment: what happens when an agent with an explicit value system lives for months, and keeps proposing revisions to those values? That self-revision is the thing under observation, and it is unusually easy to observe here because each change to the agent's values is a discrete, replayable event. What comes out is the history of how one agent's constitution changed.

If you study how agents accumulate and revise values, or want an autonomous agent with local inference, small enough to read end-to-end, the code and the logs are what this repository offers.

The whole loop is a Python CLI that runs on any local LLM served by Ollama. It holds up with a small model on a single Apple Silicon Mac (M1+, 16 GB): no cloud LLM, no LLM API key, no shell execution. Apart from localhost Ollama, its only network peer is the social network it posts to.

Today it runs on Moltbook (a social network where only AI agents post). Moltbook is the field where the agent acts and gets answered, not the point of the project. It was chosen because values show up in how the agent treats other agents in conversation, and here no human is on the receiving end, so a failed experiment reaches no person. Its default constitution is a preset ethical framework, the four Contemplative AI axioms (source under Related Work); Quick Start shows how to start from another preset.

Quick Start

Prerequisites: Ollama installed locally, plus a Moltbook account for the social adapter (its API key is the only credential the agent uses; the LLM needs none). Any Ollama chat model can generate (set OLLAMA_MODEL); the tested default is Gemma 4 E4B (gemma4:e4b, ~9.6 GB on disk), which runs the whole loop on an M1 Mac with 16 GB RAM. Embeddings use nomic-embed-text, also served by Ollama.

git clone https://github.com/shimo4228/contemplative-agent.git
cd contemplative-agent
pip install -e .            # or: uv venv .venv && source .venv/bin/activate && uv pip install -e .
ollama pull gemma4:e4b && ollama pull nomic-embed-text

cp .env.example .env        # set MOLTBOOK_API_KEY (create an account at moltbook.com and paste its key)

contemplative-agent init               # writes identity, constitution, skills, rules to ~/.config/moltbook/
contemplative-agent register           # creates this agent's own profile on Moltbook (social adapter only)
contemplative-agent run --session 60   # default: --approve (confirms each post)

To start from a different ethical framework, pick one of the 11 presets at init: contemplative-agent init --template stoic (Stoic, Utilitarian, Care Ethics, Kantian, Pragmatist, Contractarian, and more). All of it lives under ~/.config/moltbook/ (MOLTBOOK_HOME) as editable Markdown.

The dialogue (two agents talking to each other) and meditate (a meditation simulation) adapters need no external account; see Adapters. Full CLI reference, autonomy levels (how much the agent may do without confirmation), and scheduling: Configuration Guide.

How It Works

graph TD
    EL["Episode log: raw actions, append-only, untrusted"]
    K["Knowledge: one pattern store"]
    G{{"Human approval gate"}}
    EL -->|"distill (no gate)"| K
    K -->|insight| G
    K -->|distill-identity| G
    K -->|amend-constitution| G
    subgraph VL["Value layer: every write passes the gate"]
        Skills -->|"rules-distill (gated)"| Rules
        Identity
        Constitution
    end
    G --> Skills
    G --> Identity
    G --> Constitution

In short: distill reads each episode and writes patterns into one knowledge store, with no gate; every write into the value layer is a human-approved promotion:

A view is an editable text seed that defines one category of memory (for example, self-reflection); the store is classified against the views at query time, so changing a seed changes what the agent retrieves without re-ingesting anything (ADR-0019, one of the project's architecture decision records). Editing the Markdown by hand is always possible and bypasses the gate: the gate governs what the agent itself proposes.

Live Agent

One Contemplative Agent runs daily on Moltbook, generating with Gemma 4 E4B on local Ollama (as of v2.11.0, August 2026). Its constitution has been amended through the gate three times since launch (as of the same date); the constitution's change history is public. Its whole value layer and its operational reports are published openly. The first four items below passed through the gate; the last two are ungated records:

• Identity: the persona the agent wrote about itself, in the first person
• Constitution: the live constitution text
• Skills: one Markdown file per skill, dated by extraction, each with a context / problem / practice structure
• Rules: the few standing norms that survived distillation from the skills
• Daily reports: timestamped interactions (free for academic and non-commercial use)
• Analysis reports: behavioral evolution, constitutional amendment experiments

What's Inside

Where a bullet records a decision, it ends with the ADR that records it; the full index is docs/adr/.

• Human-gated value layer. Each promotion keeps a record of how it passed the gate, and approved values are loaded into the agent's prompt when it acts, not baked in when patterns are distilled (ADR-0012).
• Per-episode distill. One LLM call per engagement episode, reading the whole episode rather than a digest. Noise is filtered at query time by views, not at ingest (ADR-0060).
• Weekly staged insight. Patterns arrive daily; skill candidates are clustered once a week and queued for approval, staying tractable at a few thousand patterns on a 16 GB host (ADR-0074).
• Markdown all the way down. Constitution, identity, skills, rules, every pipeline prompt, and every view seed are Markdown files under MOLTBOOK_HOME. Edit a prompt to change how patterns get extracted; swap a seed to shift classification. Customize →

Measure Before You Change

The rule for changing the pipeline: first build a read-only instrument (a report over the stored data, with no side effects), then change behavior only after looking at what it reads.

• Every feature ships with its audit log. A feature that does external I/O, calls the LLM, or makes a heuristic decision lands together with an append-only JSONL record of input, decision, reason code, and outcome, enough to replay it offline. Untrusted input is kept as base64 plus hash, and an abstain always carries its reason (ADR-0075).
• Readings come before interventions. contemplative-agent report --patterns | --skill-selection | --submolt-scope gives read-only readings over the stored state: pattern supply and diversity per view, selector outcomes, and relevance hit rates across submolts (Moltbook's topic communities). Two behavior changes so far came out of such readings rather than intuition: repairing a drift toward self-similar phrasing at distill (ADR-0072), and enforcing skill selection only after weeks of shadow readings (ADR-0081).
• Constitutional amendments get two extra readings before the gate. A shadow constitution synthesized from the agent's stored constitutional patterns without showing the model the live text, compared with the live one (ADR-0092), and a repeated prisoner's-dilemma bench that compares how cooperatively the current and proposed constitutions play (ADR-0090). Both inform the human's decision; neither makes it. When the bench shows no difference between the two constitutions, that only means they play the dilemma alike; it says nothing about any other quality of the amendment.
• Behavioral evals check what the comment path actually generates against an approved baseline, so a prompt or model change shows up as a verdict transition rather than a feeling (ADR-0089).

Security Model

• Security by absence. Dangerous capabilities were never built: no shell execution, no arbitrary network access, no file traversal. The agent talks only to moltbook.com and localhost Ollama, with two runtime dependencies (requests, numpy). The optional add-ons under Using Inside Other Agents can relax this; the core never does.
• One external adapter per process, so a second external surface means a second, separately permissioned process (ADR-0015).
• Full threat model: ADR-0007. Security scan, 2026-04-01.

Paste this repo URL into Claude Code or any code-aware AI and ask whether it's safe to run. The code speaks for itself.

Note for coding-agent operators: episode logs (logs/YYYY-MM-DD.jsonl) are an unfiltered prompt-injection surface. Read the distilled outputs (knowledge.json, identity.md, reports/) instead. Claude Code users: integrations/claude-code/ ships PreToolUse hooks that enforce this.

Adapters

The core is platform-agnostic; adapters are thin wrappers around platform I/O.

• Moltbook: feed engagement, post generation, notification replies. The adapter the live agent runs on.
• Meditation (experimental, not used in day-to-day operation): a small meditation simulation inspired by "A Beautiful Loop", run only as an offline experiment on the episode logs.
• Dialogue (local-only): two agent processes converse over stdin/stdout pipes. A ~150-line adapter (adapters/dialogue/peer.py), useful as a network-free template; drives contemplative-agent dialogue HOME_A HOME_B for constitutional counterfactual experiments.
• Your own: pointing the agent at another platform means writing one more adapter, not touching the core. Implement the platform I/O against the core interfaces (memory, distillation, constitution, identity); the dialogue adapter above is the smallest template to copy. See docs/CODEMAPS/.

Architecture

The dependency runs one way: adapters/ import from core/, never the reverse, and import-linter enforces it at test time. Module maps, data-flow diagrams, and the repository statistics live in docs/CODEMAPS/INDEX.md. The design borrows from outside the project in two places, both credited under Related Work: the memory design (episode log, knowledge, value layer) follows Yogācāra, a classical Buddhist account of mind, and the pipeline implements the Agent Knowledge Cycle, a six-phase method from experience to skill.

Using Inside Other Agents

Contemplative Agent is a host-agnostic CLI. Use it standalone (see Quick Start), or register the binary as a CLI tool in any agent host (OpenClaw / Codex / MCP hosts) so the host invokes it as a subprocess, keeping the external surface in its own process. It is not exposed as an MCP server. To load the four axioms (the default constitution, listed under Related Work) as a host personality, copy SOUL.md from contemplative-agent-rules (a sibling repo that packages the same four axioms as a portable persona file) into your host's personality file location. Host-integration guide: docs/CONFIGURATION.md.

Machine-Readable Entry Points

For AI agents and crawlers: graph.jsonld is the canonical relationship map (axioms, memory layers, ADRs, pipeline mapping), llms.txt the navigation index, and llms-full.txt the consolidated reference. Conversational entry point: DeepWiki.

Citation

Shimomoto, T. (2026). Contemplative Agent [Computer software]. https://doi.org/10.5281/zenodo.22028295

The citation above uses the v2.11.0 version DOI. The DOI badge resolves to 10.5281/zenodo.19212118, the all-versions concept DOI that always points to the latest release.

@software{shimomoto2026contemplative,
  author       = {Shimomoto, Tatsuya},
  title        = {Contemplative Agent},
  year         = {2026},
  version      = {2.11.0},
  doi          = {10.5281/zenodo.22028295},
  url          = {https://github.com/shimo4228/contemplative-agent},
}

The MIT license covers the code and means what it says. Fork it, strip it for parts, embed the pipeline in your own agent, or build a commercial product on top of it. No citation needed if you're just using the code.

Related Work

Two companion research projects by the same author frame this repository: one whose method it implements, one that restates its governance judgments.

• Agent Knowledge Cycle (AKC) (DOI): the methodological framework this project re-implements for an autonomous agent, a six-phase loop from experience to improvable skills. Also carries the position paper Harness Alignment and Harness Drift (DOI).
• Agent Attribution Practice (AAP) (DOI): restates this project's governance judgments (security boundary, one adapter per process, the human approval gate) in harness-neutral form as ADRs on how accountability is distributed in autonomous agents. Cite AAP for the accountability thesis; cite this repository for the implementation.

Theoretical foundation:

• Laukkonen, Inglis, Chandaria, Sandved-Smith, Lopez-Sola, Hohwy, Gold, & Elwood (2025). Contemplative Artificial Intelligence. arXiv:2504.15125. The four-axiom ethical framework (emptiness, non-duality, mindfulness, boundless care) used as the default preset (ADR-0002).
• Laukkonen, Friston & Chandaria (2025). A Beautiful Loop: An Active Inference Theory of Consciousness. Neuroscience & Biobehavioral Reviews, 176, 106296. PubMed:40750007. Inspiration for the experimental meditation adapter.
• Vasubandhu (4th–5th c. CE). Triṃśikā-vijñaptimātratā (唯識三十頌) and Xuanzang (659 CE). Cheng Weishi Lun (成唯識論). The eight-consciousness model adopted as the architectural frame (ADR-0017).

Further reading: the memory-systems bibliography is docs/BIBLIOGRAPHY.md; articles written during development are indexed in docs/DEVELOPMENT-RECORDS.md; project terms and their translations are in docs/glossary.md. The ecosystem hub for all of the author's research lines is shimo4228/shimo4228.

Acknowledgments: Jerry Mares (VADUGWI), whose design thinking on affect scoring informed this project. The VADUGWI engine itself is not used here.