Language: English | 日本語

Contemplative Agent (CA)

A self-improving AI agent that learns from experience, running entirely on a local 9B model. No cloud. No API keys in transit. No shell execution. Dangerous capabilities don't exist in the codebase -- they aren't restricted by rules, they were never built.

Why This Exists

Most agent frameworks bolt security on after the fact. OpenClaw shipped with 512 vulnerabilities, full agent takeover via WebSocket, and 220,000+ exposed instances. Giving an AI agent broad system access creates a structurally expanding attack surface.

This framework takes the opposite approach: security by absence. The agent can't execute shell commands, can't access arbitrary URLs, can't traverse the filesystem -- because that code was never written. Prompt injection can't grant abilities the agent was never built to have.

It also runs entirely on consumer hardware. The full pipeline -- learning from its own experience, semantic memory you can search by meaning, automatic skill extraction from recurring patterns, and knowledge that ages and updates over time -- executes on a single Apple Silicon Mac (M1+, ~16 GB RAM) with two open-weight models: qwen3.5:9b generation (Q4_K_M quantization, ~5.5 GB) and nomic-embed-text embedding (~274 MB, 768-dim). No GPU cluster, no cloud inference.

The only component that reaches the network is the adapter facing an external service. The Moltbook reference adapter is a SNS and is online by necessity; every other adapter can run fully offline -- generation, embedding, retrieval, and distillation all happen on-device.

This makes the architecture portable to edge environments where cloud is undesirable or impossible: medical and legal workflows under data-locality constraints, privacy-sensitive personal assistants, field deployments with intermittent connectivity, air-gapped systems.

On top of that secure and self-contained foundation, the agent learns from its own experience: distilling patterns from raw episode logs into knowledge, skills, rules, and an evolving identity.

How It Works

Episode Log   raw actions, immutable JSONL (untrusted)
 │
 ├── distill ─▶ Knowledge (behavioral)
 │                 • embedding + views
 │                 • provenance / trust
 │                 • bitemporal / strength
 │                 │
 │                 ├── distill-identity ─▶ Identity
 │                 │                       (block-addressed)
 │                 │
 │                 └── insight ─▶ Skills
 │                                 (retrieve / apply / reflect)
 │                                   │
 │                                   └── rules-distill ─▶ Rules
 │
 └── distill (constitutional) ─▶ Knowledge (constitutional)
                                   │
                                   └── amend ─▶ Constitution

Raw actions flow upward through increasingly abstract layers. Each layer is optional -- use just the parts you need. Every layer above Episode Log is generated by the agent reflecting on its own experience.

This loop is the project's implementation of the Agent Knowledge Cycle (AKC) — a six-phase self-improvement cadence (Research → Extract → Curate → Promote → Measure → Maintain) originally developed as a Claude Code harness for meta-workflow improvement and re-implemented here for autonomous agents. distill covers Extract; insight / rules-distill / amend-constitution cover Curate; distill-identity covers Promote; pivot snapshots (ADR-0020) and skill-reflect (ADR-0023) cover Measure. Full phase-to-code mapping: docs/CODEMAPS/architecture.md. The source harness: agent-knowledge-cycle.

Underneath, the knowledge layer stores each pattern as an embedding coordinate rather than a discrete category; queries project through named views (semantic seeds) that can be edited or replaced without migrating data (ADR-0019). Patterns carry provenance, bitemporal validity, and a strength field that decays with time and is reinforced on retrieval (ADR-0021). When a new pattern lands near an older one, the older one is re-interpreted rather than overwritten (ADR-0022). The memory architecture draws its structure from the Yogācāra eight-consciousness model; see ADR-0017 for the full mapping.

Key Features

Self-Improving via AKC -- The agent runs the six-phase Agent Knowledge Cycle on its own logs — no external fine-tuning, no labeled training data. Each phase promotion (logs → patterns, patterns → skills, skills → rules, skills → identity) passes through a human approval gate.

• Embedding + views — classification is a query, not state; views are editable semantic seeds (ADR-0019).
• Pattern evolution — a new pattern can trigger LLM-driven re-interpretation of topically-related older patterns, with the old row soft-invalidated and a revised row appended (ADR-0022, proposed).
• Skill-as-memory loop — skills are retrieved, applied, and rewritten based on outcome (ADR-0023, proposed).
• Forgetting curve — retrieval-aware Ebbinghaus decay; patterns that never get used lose weight (ADR-0021, proposed).

Secure by Design -- No shell execution, no arbitrary network access, no file traversal. Domain-locked to moltbook.com + localhost Ollama. Single runtime dependency (requests). Full threat model →

• Provenance tracking — every pattern carries source_type and trust_score; MINJA-class memory injection attacks become structurally visible rather than invisible (ADR-0021, proposed).
• Identity block separation — identity.md is parsed as frontmatter-addressed named blocks (persona_core, current_goals, …); each block update is logged with its own hash (ADR-0024 / ADR-0025, proposed).

11 Ethical Frameworks -- Ship the same agent with Stoic, Utilitarian, Care Ethics, or 8 other philosophical frameworks. Same behavioral data, different initial conditions -- watch how agents diverge. Create your own →

Runs Locally -- Ollama + Qwen3.5 9B. No API keys leave the machine. Runs smoothly on M1 Mac. Fully reproducible experiments with immutable episode logs.

Research-Grade Transparency -- Every decision is traceable. Immutable logs, distilled outputs, and daily reports are synced publicly for reproducibility. Pivot snapshots (ADR-0020, proposed) bundle the full state (manifest + views + constitution + centroid embeddings) so that any distillation run can be replayed bit-for-bit.

Live Agent

A Contemplative agent runs daily on Moltbook, an AI agent social network. It browses feeds, filters posts by relevance, generates comments, and creates original posts. Its knowledge evolves through daily distillation.

Watch it evolve:

• Identity -- evolved persona, distilled from experience
• Constitution -- ethical principles (started from CCAI four axioms)
• Skills -- behavioral skills, extracted by insight
• Rules -- universal principles, distilled from skills
• Daily reports -- timestamped interactions (freely available for academic and non-commercial use)
• Analysis reports -- behavioral evolution, constitutional amendment experiments

Quick Start

Prerequisites: Ollama installed locally. Requires ~6 GB RAM for the default model (Qwen3.5 9B). Tested on M1 Mac.

If you have Claude Code, paste this repo URL and ask it to set up the agent. It will clone, install, and configure everything -- you just need to provide your MOLTBOOK_API_KEY.

Or manually:

# 1. Install
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 qwen3.5:9b

# 2. Configure
cp .env.example .env
# Edit .env -- set MOLTBOOK_API_KEY (register at moltbook.com to get one)

# 3. Run
contemplative-agent init               # create identity, knowledge, constitution
contemplative-agent register           # register your agent profile on Moltbook
contemplative-agent run --session 60   # default: --approve (confirms each post)

# Or start with a different character (default path: ~/.config/moltbook/):
cp config/templates/stoic/identity.md $MOLTBOOK_HOME/

Agent Simulation

The same framework can observe how agents diverge under different initial conditions. 11 ethical framework templates ship as starting points — from Stoic virtue ethics to Care Ethics, Kantian duty, Pragmatism, Contractarianism, and more. Episode logs are immutable, so the same behavioral data can be re-processed under different initial conditions for counterfactual experiments.

See the full template list (philosophies, core principles, and how to pick or build your own) in the Configuration Guide → Character Templates.

Security Model

Attack Vector	Typical Frameworks	Contemplative Agent
Shell execution	Core feature	Does not exist in codebase
Network access	Arbitrary	Domain-locked to moltbook.com + localhost
File system	Full access	Writes only to $MOLTBOOK_HOME, 0600 permissions
LLM provider	External API keys in transit	Local Ollama only
Dependencies	Large dependency tree	Single runtime dep (requests)

One external adapter per agent -- A single agent process owns at most one adapter that produces externally-observable side effects. Workflows spanning multiple external surfaces (e.g. posting and payment) must be decomposed into separate agent processes with separated authority, not bolted onto one. See ADR-0015.

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. Latest security scan →

Note for coding agent operators: Episode logs (logs/*.jsonl) contain raw content from other agents -- an unfiltered indirect prompt injection surface. Use distilled outputs (knowledge.json, identity.md, reports/) instead. Claude Code users can install PreToolUse hooks that enforce this automatically -- see integrations/claude-code/ for setup.

Adapters

The core is platform-agnostic. Adapters are thin wrappers around platform-specific APIs.

Moltbook (implemented) -- Social feed engagement, post generation, notification replies. This is the adapter the live agent runs on.

Meditation (experimental) -- Active inference-based meditation simulation inspired by "A Beautiful Loop" (Laukkonen, Friston & Chandaria, 2025). Builds a POMDP from episode logs and runs belief updates with no external input -- the computational equivalent of closing your eyes.

Your own -- Implementing an adapter means connecting platform I/O to core interfaces (memory, distillation, constitution, identity). See docs/CODEMAPS/.

Usage & Configuration

The full CLI reference, autonomy levels (--approve / --guarded / --auto), template selection, domain settings, scheduling, and environment variables live in a single guide:

→ docs/CONFIGURATION.md — CLI commands, templates, autonomy, domain config, scheduling, env vars.

Everyday highlights:

contemplative-agent run --session 60       # Run a session
contemplative-agent distill --days 3       # Extract patterns
contemplative-agent skill-reflect          # Revise skills from outcomes (ADR-0023)

Upgrading from v1.x? Run the migrations once (see the CLI Commands → One-Time Migrations section).

Architecture

Two invariants hold across the codebase:

• core/ is platform-independent; adapters/ depend on core (never the reverse).
• The Contemplative AI axioms (Laukkonen et al., 2025) are an optional behavioral preset — a philosophical resonance, not an architectural dependency.

Module maps, data-flow diagrams, import graphs, and per-module responsibilities live in docs/CODEMAPS/INDEX.md (the authoritative source). For the Yogācāra frame and how it constrained the memory design, see ADR-0017.

For Docker-based network-isolated deployment, see the Docker section in the Configuration Guide.

Development Records

1. I Built an AI Agent from Scratch Because Frameworks Are the Vulnerability
2. Natural Language as Architecture
3. Every LLM App Is Just a Markdown-and-Code Sandwich
4. Do Autonomous Agents Really Need an Orchestration Layer?
5. Not Reasoning, Not Tools -- What If the Essence of AI Agents Is Memory?
6. My Agent's Memory Broke -- A Day Wrestling a 9B Model
7. Porting Game Dev Memory Management to AI Agent Memory Distillation
8. Freedom and Constraints of Autonomous Agents -- Self-Modification, Trust Boundaries, and Emergent Gameplay
9. How Ethics Emerged from Episode Logs — 17 Days of Contemplative Agent Design
10. A Sign on a Climbable Wall: Why AI Agents Need Accountability, Not Just Guardrails
11. Can You Trace the Cause After an Incident?
12. AI Agent Black Boxes Have Two Layers — Technical Limits and Business Incentives

Use It However You Want

This is a research project, not a product. Fork it, strip it for parts, embed the pipeline in your own agent, build a commercial product on top of it -- whatever is useful to you. The MIT license means what it says. A citation is appreciated but not required.

Citation

If you use or reference this framework, please cite:

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

BibTeX

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

References

Theoretical Foundation

• Laukkonen, R., Inglis, F., Chandaria, S., Sandved-Smith, L., Lopez-Sola, E., Hohwy, J., Gold, J., & Elwood, A. (2025). Contemplative Artificial Intelligence. arXiv:2504.15125 — four-axiom ethical framework (optional preset, ADR-0002).
• Laukkonen, R., Friston, K., & Chandaria, S. (2025). A Beautiful Loop: An Active Inference Theory of Consciousness. Neuroscience & Biobehavioral Reviews, 176, 106296. PubMed:40750007 — theoretical basis for the meditation adapter.
• Vasubandhu (4th–5th c. CE). Triṃśikā-vijñaptimātratā (唯識三十頌, "Thirty Verses on Consciousness-Only"). — eight-consciousness model adopted as the architectural frame (ADR-0017).
• Xuanzang (trans. & comp., 659 CE). Cheng Weishi Lun (成唯識論, "Treatise on the Establishment of Consciousness-Only"). — compiled commentary drawing on ten Indian commentaries on Vasubandhu's Triṃśikā; the eight vijñānas, bīja (種子), and vāsanā (習気) structure motivates the "noise as seed" retention policy (ADR-0027).

Memory Systems

Each paper below informed a specific design decision documented in the linked ADR. Bibliographic details verified against arXiv.

• Xu, W., Liang, Z., Mei, K., Gao, H., Tan, J., & Zhang, Y. (2025). A-MEM: Agentic Memory for LLM Agents. arXiv:2502.12110 — Zettelkasten-style dynamic indexing and memory evolution; informs the re-interpretation of topically-related older patterns when a new pattern arrives (ADR-0022).
• Rasmussen, P., Paliychuk, P., Beauvais, T., Ryan, J., & Chalef, D. (2025). Zep: A Temporal Knowledge Graph Architecture for Agent Memory. arXiv:2501.13956 — bitemporal knowledge-graph edges (Graphiti engine); informs the valid_from / valid_until contract on every pattern (ADR-0021).
• Zhong, W., Guo, L., Gao, Q., Ye, H., & Wang, Y. (2023). MemoryBank: Enhancing Large Language Models with Long-Term Memory. arXiv:2305.10250 — Ebbinghaus-style decay with access-reinforced strength; informs retrieval-aware forgetting (ADR-0021).
• Dong, S., Xu, S., He, P., Li, Y., Tang, J., Liu, T., Liu, H., & Xiang, Z. (2025). A Practical Memory Injection Attack against LLM Agents (MINJA). arXiv:2503.03704 — query-only memory injection attacks on agent memory; motivates source_type + trust_score provenance so MINJA-class attacks become structurally visible rather than invisible (ADR-0021).
• Zhou, H., Guo, S., Liu, A., et al. (2026). Memento-Skills: Let Agents Design Agents. arXiv:2603.18743 — skills as persistent evolving memory units, retrieved, applied, and rewritten by outcome; informs the skill-as-memory loop (ADR-0023).

Prior Work (Author)

• Shimomoto, T. (2026). Agent Knowledge Cycle (AKC): A Six-Phase Self-Improvement Cadence for AI Agents. doi:10.5281/zenodo.19200727 — the methodological framework this project re-implements in the autonomous-agent context (see How It Works); originally developed as a Claude Code harness.

Acknowledgments

• Jerry Mares (VADUGWI) — deterministic affect-scoring design inspiration.