Your AI agent forgets.
Give it a soul.

Persistent identity, knowledge, and memory for AI coding agents. Built on Markdown and Git. Works with any CLI tool.

View on GitHub Get Started
Claude Code Gemini CLI Codex CLI Cursor

Without Agent Souls

  • Agent doesn't know your naming conventions
  • Repeats yesterday's mistakes
  • Suggests patterns you've rejected before
  • You re-explain everything. Every. Session.

With Agent Souls

  • Agent loads its identity and hard rules
  • Checks past mistakes before starting
  • Loads domain cheatsheets on demand
  • Writes back what it learned when done
agents/aerospace/miles/
CORE.md ← "Lead aerodynamicist. Starts every analysis with a back-of-envelope sanity check. Distrusts any result that violates physical intuition." cheatsheets/ stability-derivatives.md [TEXTBOOK] reference axis systems, sign conventions x-tail-configurations.md [DERIVED] roll coupling effects worked out in session common-unit-pitfalls.md [VERIFIED] mistakes caught in real analysis memory/ mistakes.md ← "Forgot to convert Cm_alpha from /rad to /deg. Sanity check caught it — 57x too large." decisions.md ← "Used body-axis over stability-axis: decouples lateral modes at high alpha." session-log.md ← full history of every past session

How It Works

Every session follows the same cycle: load, work, learn, save.

1

Summon

Agent loads its CORE.md (identity and rules), checks mistakes.md (past errors to avoid), and scans the cheatsheet index for available knowledge.

2

Work

Agent loads relevant cheatsheets on demand. Only what's needed for the current task enters context — no bloat, no full textbook dumps.

3

Learn

During the session, the agent can study new source material and distill it into cheatsheets with confidence tags: [VERIFIED], [TEXTBOOK], [DERIVED].

4

Save

Session end protocol: log what happened, record mistakes, update cheatsheets, commit to Git. Next session starts where this one left off.

Works With Your Tools

Native integrations, not wrappers. Each tool loads agents through its own mechanism.

Claude Code

Auto-discovered from .claude/agents/

Native

Gemini CLI

Via AGENTS.md or skill files

Compatible

Codex CLI

Reads AGENTS.md automatically

Compatible

Cursor

Reference paths in .cursorrules

Compatible

Get Started in 2 Minutes

Clone, summon an agent, see it work. Then fork it and make your own.

$ git clone https://github.com/sezersivri/agentsouls.git $ cd agentsouls $ claude # or gemini, or codex # Try the example agents: > Ask Miles to analyze the stability derivatives > Use Sam for the backend API implementation # Then make it yours: $ fork → make private → delete examples → create your own # Full guide: docs/PRIVATE-SETUP.md
Read the Private Setup Guide

Agents are personal.
Build yours.

Fork the repo, make it private, create agents that know your workflow.

Fork on GitHub Star