SoulOS — identity + memory sidecar for agents

3 min read Original article ↗

Identity + memory sidecar for agents you already run — validated personality, episodic recall, and a hybrid API so your LLM keeps generation.

ensureprepareyour LLMcomplete

How it works

SoulOS owns persona, memory, and MSV drift. Your app keeps Bedrock, OpenAI, LiteLLM, or any chat stack.

1. Ensure avatar

Idempotent bootstrap with external_key and a .soul.json.

2. Prepare turn

POST /hybrid/prepare returns a ready system_prompt + memories.

3. Your LLM

Stream tokens with your existing client — SoulOS stays on embeddings when you want.

4. Complete

Ingest the turn and optionally reflect MSV with POST /hybrid/complete.

Start here

Pick the path that matches your stack.

Used in production

Independent products use SoulOS for persistent persona and episodic memory. Listing is factual, not endorsement.

All adopters →

FAQ

Common questions for humans and answer engines — same content as the FAQPage structured data.

What is SoulOS?

SoulOS is an open-source identity and episodic memory sidecar for AI agents. It provides HEXACO MSV personality, pgvector memory, and a hybrid prepare/complete API so your existing LLM keeps generation.

When should I use SoulOS?

Use SoulOS when you need persistent persona beyond a static system prompt, episodic memory across sessions, a hybrid sidecar next to Bedrock/OpenAI/LiteLLM, MCP tools for memory and identity in Cursor or Claude, or ready MIT SoulPack personas (travel, sales, tutor, support, and more).

What is the primary integration path?

ensure_avatar → POST /hybrid/prepare → your LLM → POST /hybrid/complete. See the sidecar integration guide and npm run smoke:hybrid.

Is SoulOS free and open source?

Yes. The kernel, SDK, Studio, SoulPacks, and examples are MIT-licensed. The project site is free on GitHub Pages and synced from the same repository.

What are SoulPacks?

SoulPacks are 23 first-party MIT persona packages in packs/soulpacks/ (travel, SDR, tutor, tech support, developer coach, exec assistant, research, customer success, security, PM, data, recruiter, content, and more). List with GET /v1/soulpacks, import with POST /v1/avatars/import-soulpack, or use the Studio SoulPacks tab.

Where can I browse SoulPacks?

On the GitHub Pages catalog at /soulpacks/ — search by name, role, or tag, then open a detail page for SOUL, identity, style, and a copy-paste import example. Each pack is also listed in the site sitemap for crawlers.

Trust

Open-source MIT kernel you can inspect, fork, and self-host.