agent-soul

What problem does it solve?

This Skill solves the problem of AI agents forgetting and desynchronizing across sessions, devices, and different runtimes by providing a shared, durable memory and persona stored in a user-controlled Git repository.

Core Features & Use Cases

• Persistent identity (L0 Soul): keeps one consistent assistant persona across runtimes using SOUL.md, IDENTITY.md, USER.md, and VOICE.md.
• Durable shared memory (L1 Memory): compiles event-based facts into canonical/profile.md and canonical/stable-memory.md.
• On-demand context (L2 Context): loads project, fuzzy, and provenance context only when needed to keep context lightweight.
• Append-only event surface with expiry: writes NDJSON events to sources/<source> and supports valid_until for time-bound facts.
• Cross-agent synchronization: makes new learnings available to other agents by compiling sources into canonical/* via scripts and CI.
• Auditability and portability: avoids databases and memory APIs by using Git as the storage and distribution layer.

Quick Start

Use the agent-soul skill by cloning your template into a private repo, filling SOUL.md, IDENTITY.md, USER.md, and VOICE.md, then telling your AI runtime to follow JOIN.md and to write join events with scripts/add_event.py using a stable source id.