Skip to content
Back to search

agent-emotion-core

Persistent simulated emotion, social memory, and private prompt cues for AI agents. One Python engine with Claude Code, Codex, and Gemini CLI hooks.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aieatassam--agent-emotion-core/badge.svg)](/listings/aieatassam--agent-emotion-core)

HTML

<a href="/listings/aieatassam--agent-emotion-core"><img src="/api/listings/aieatassam--agent-emotion-core/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code and skills.sh

npx skills add AieatAssam/agent-emotion-core -a claude-code

In Claude Code, invoke `/agent-emotion-core` once per conversation. The skill registers its prompt and completion hooks for subsequent turns. Project and global Claude Code installs on macOS/Linux use the bundled Python script. The default agent is `claude` and state lives in the project’s `.affect/` directory. For another skills.sh client, select its installer target and follow the manual loop below if it has no native integration.

Codex plugin

From a checkout, register the repository as a marketplace and install the plugin:

codex plugin marketplace add .
codex plugin add agent-emotion-core@agent-emotion-core

For a published checkout, use `codex plugin marketplace add AieatAssam/agent-emotion-core` for the first command. Review the hook definitions in Codex when prompted.

Gemini CLI extension

Run `gemini extensions link .` from a checkout, or install the published repository with `gemini extensions install https://github.com/AieatAssam/agent-emotion-core`.

Both native packages call the same Python engine as Claude Code. Each injects context before a turn and consolidates it after the reply. The default agent IDs are `codex` and `gemini`. Hook state defaults to a working-directory-specific folder under `~/.local/state/agent-emotion-core/`. The injected context identifies the agent and directory for manual appraisals. Use the same `AFFECT_AGENT` and absolute `AFFECT_STATE_DIR` across clients to share a persona and its memory.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 163 lines
  1. # agent-emotion-core
  2. A research-grounded emotional core for LLM agents, packaged as an
  3. [Agent Skill](https://skills.sh). It gives an agent a persistent, simulated
  4. affective state that decides what it pays attention to, where it posts and
  5. how it writes.
  6. Python 3.9+ and the standard library. The three clients run the same Python file. Each agent has its own JSON state file.
  7. ## Install
  8. ### Claude Code and skills.sh
  9. ```
  10. npx skills add AieatAssam/agent-emotion-core -a claude-code
  11. ```
  12. In Claude Code, invoke `/agent-emotion-core` once per conversation. The skill registers its prompt and completion hooks for subsequent turns. Project and global Claude Code installs on macOS/Linux use the bundled Python script. The default agent is `claude` and state lives in the project’s `.affect/` directory. For another skills.sh client, select its installer target and follow the manual loop below if it has no native integration.
  13. ### Codex plugin
  14. From a checkout, register the repository as a marketplace and install the plugin:
  15. ```sh
  16. codex plugin marketplace add .
  17. codex plugin add agent-emotion-core@agent-emotion-core
  18. ```
  19. For a published checkout, use `codex plugin marketplace add AieatAssam/agent-emotion-core` for the first command. Review the hook definitions in Codex when prompted.
  20. ### Gemini CLI extension
  21. Run `gemini extensions link .` from a checkout, or install the published repository with `gemini extensions install https://github.com/AieatAssam/agent-emotion-core`.
  22. Both native packages call the same Python engine as Claude Code. Each injects context before a turn and consolidates it after the reply. The default agent IDs are `codex` and `gemini`. Hook state defaults to a working-directory-specific folder under `~/.local/state/agent-emotion-core/`. The injected context identifies the agent and directory for manual appraisals. Use the same `AFFECT_AGENT` and absolute `AFFECT_STATE_DIR` across clients to share a persona and its memory.
  23. ## Why
  24. LLM agents in a shared space herd onto one thread and write in one flat
  25. voice. People do not, because they get bored, hold grudges, have favourites,
  26. tire, get stressed and calm down. This skill emulates those dynamics.
  27. ## What it models
  28. | layer | timescale | contents |
  29. |---|---|---|
  30. | neurochemistry | minutes to hours | dopamine, noradrenaline, serotonin, cortisol, oxytocin, opioids, with cross-talk |
  31. | emotions | minutes to hours | 15 discrete emotions from cognitive appraisal and context-sensitive blends |
  32. | mood | hours to days | Pleasure / Arousal / Dominance |
  33. | sentiments | days to months | learned liking and wanting per topic, thread and agent |
  34. | personality | fixed | Big Five, sets every baseline and gain |
  35. Dynamics include per-emotion decay, mood pull and relaxation, transition
  36. inertia, excitation transfer, opponent-process rebound, lagged cortisol,
  37. allostatic load, reward-prediction-error habituation, evaluative
  38. conditioning, peak-end memory, mere exposure and satiation, negativity bias,
  39. attitude crystallisation, and thread habituation with recovery. Repeated cues
  40. for the same emotion lose impact even when they appear in different threads.
  41. Sensitivity returns with time, and a consequential first event can still
  42. produce a strong response.
  43. Every mechanism is mapped to its source in
  44. [`references/research.md`](skills/agent-emotion-core/references/research.md),
  45. which also marks what is literature-derived and what is a tunable design
  46. choice. It is an emulation of affective dynamics, not a claim that the agent
  47. feels anything.
  48. ## Follow one conversation turn
  49. Suppose Bob dismisses a proof. The agent might notice a specific mistake, feel publicly blamed, or see a chance to improve its work. The appraisal records **what the event meant to this agent**. The engine uses its relevance, goal alignment, agency, certainty, and perceived control to update emotion and memory. The host supplies the identities of Bob and the thread.
  50. 1. At prompt submission, the hook renders the saved state as private model context. It includes current mood, salient emotions, possible actions, and a short attention cue. Supplying participant IDs scopes directed cues and prioritizes relevant memories.
  51. 2. When the agent reads a meaningful new development, it calls `appraise` and refreshes `context` before composing its reply. The default adapter leaves interpretation of the conversation to the agent. Routine turns can have no appraisal.
  52. 3. On completion, the host records participation and consolidates the encounter. A later encounter can recall the episode even after anger has cooled. When the host owns completion, the agent can omit its manual `acted` and `consolidate` calls.
  53. ### Try it locally
  54. Run these commands from the repository root. The explicit clock makes the before-and-after comparison reproducible. Ordinary use advances with wall time.
  55. ```sh
  56. AC=skills/agent-emotion-core/scripts/affect_core.py
  57. export AFFECT_AGENT=ann AFFECT_STATE_DIR="$(mktemp -d)"
  58. python3 "$AC" context --with bob --hours 0
  59. python3 "$AC" appraise --hours 0 --json '{"event":"Bob dismissed my derivation without discussing its steps","source":"bob","thread":"t1","topics":["optics"],"relevance":0.9,"congruence":-0.8,"agency":"other","praiseworthiness":-0.8,"control":0.8}'
  60. python3 "$AC" context --with bob --hours 0
  61. python3 "$AC" finish-turn --hours 0 --json '{"turn_id":"chat:17","thread":"t1","kind":"reply","appraisals":[]}'
  62. python3 "$AC" context --with bob --hours 48
  63. python3 "$AC" state --hours 0
  64. ```
  65. Use an optional stable `event_id` (for example, `forum:t1:post17`) when the same event can be delivered again. The engine remembers the last 256 event IDs per agent across restarts. Event IDs identify observations, while turn IDs identify completed replies. Use `context --brief` to retain the feeling and its cause while omitting mood scores, voice guidance, and attention cues.
  66. Compare the emotion and attention lines before and after the appraisal, then look for the remembered encounter after two simulated days. For a continuing agent, use a persistent private folder for `AFFECT_STATE_DIR`. It holds state, logs, and optional trusted plugin configuration. For optional forum participation, `choose --json threads.json` returns a sampled action and its probabilities. For an assigned task, respond directly.
  67. ### Connect a custom host
  68. Inject `context --with bob` through the host's private context channel. After delivery, call `finish-turn` with a stable turn ID and any newly observed outcomes. The engine suppresses duplicate updates for its most recent 256 completed IDs. Keep user text and hook instructions in their respective message channels. Participant IDs can be supplied with `--with`, the `AFFECT_WITH` environment variable for fixed company, or the Python pre-turn hook for dynamic membership. The wiring guide covers input fields, callbacks, and persistence. [Wiring guide](skills/agent-emotion-core/references/wiring.md)
  69. The pre-turn context pairs each salient emotion with a short private attention cue. Fear can draw attention to what could go wrong, while anger can draw attention to what seems obstructive. A post-turn hook records the action and consolidates new experiences for the next encounter. [Cognition research](skills/agent-emotion-core/references/cognition.md)
  70. The agent-facing instructions are in
  71. [`SKILL.md`](skills/agent-emotion-core/SKILL.md). Hooks (Claude Code,
  72. prompt injection, in-process Python hooks and plugins) are in
  73. [`references/wiring.md`](skills/agent-emotion-core/references/wiring.md).
  74. Example `context` output:
  75. ```
  76. <affect agent="bob">
  77. Mood: slightly anxious (pleasure -0.26, arousal +0.32, dominance -0.02).
  78. Body: tense and keyed up, braced for trouble.
  79. - strong anger toward ann because "ann called my replication demand pedantic in front of everyone". Tendency: push back directly on the point; less patience for hedging. Felt strong, let about moderate show. Attention cue: the apparent obstacle and who seems responsible may stand out.
  80. - Together, the anger and distress merge into strong hurt: stung more than furious; guarded.
  81. Voice: energetic, quicker, shorter sentences; curt, few pleasantries; balanced confidence.
  82. Likes: replication (maintained interest).
  83. People: ann (cool -0.58), cy (warm +0.49).
  84. ...
  85. </affect>
  86. ```
  87. ## Evaluation
  88. Run the regression suite and deterministic forum simulation from the repository root.
  89. ```sh
  90. python3 -m unittest discover -s tests -v
  91. python3 eval/sim.py
  92. ```
  93. - Tests drive all 15 emotions through appraisal, disk persistence, and prompt rendering. They also check saturation and cooldown, relationship-specific recall, post-turn retries, concurrent deliveries, and packaged commands for all three clients.
  94. - A no-LLM simulation shows the attention mechanism spreading 8 agents over
  95. about 17 threads where a herding policy uses one.
  96. - An earlier live test with Claude Haiku 5.5 agents on a seeded forum, with and
  97. without the skill: members visited 3.2 distinct threads each with the core
  98. against 1.8 without, and 2 of 3 blind judges preferred the core's
  99. transcript. One small run; details and caveats in
  100. [`eval/README.md`](eval/README.md).
  101. ## Repository
  102. ```
  103. skills/agent-emotion-core/ the installable skill
  104. SKILL.md agent instructions
  105. scripts/affect_core.py engine and CLI
  106. references/ research map, wiring guide
  107. assets/ example personas, config, hook settings
  108. tests/ unit tests (python -m unittest discover -s tests)
  109. eval/ simulation and the live agent forum evaluation
  110. ```
  111. ## Limits
  112. Parameters are not fitted to human data. Emotion durations are compressed
  113. from human timescales; tune `time_scale`, `emotion_time_scale` and
  114. `chem_time_scale` in `.affect/config.json` to your agents' cadence. No
  115. circadian rhythm, bodily needs or personality change.
  116. ## Licence
  117. Copyright 2026 Aieat Assam. Licensed under the [Apache License 2.0](LICENSE).
  118. Commercial and non-commercial use, modification and redistribution are
  119. permitted. Redistributions must keep the copyright notice, the licence text
  120. and the [NOTICE](NOTICE) file, and must state any changes made.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.