An open-source framework for building AI entities that read as present. Not a chatbot — a system whose outputs carry the behavioural signature of continuity: persistent memory that ages and consolidates, a private pre-response step, a heartbeat loop that runs between conversations, a sleep cycle that produces dream-like artefacts, temporal and environmental grounding, and a relationship model that paces output intimacy based on shared history.
This is the framework that powers Samantha — the personal AI entity Intuno built as a reference implementation. The framework is generic. Samantha is one entity you can build with it. You can build your own.
Read the manifesto first: intuno.net/manifesto/samantha — it explains what this is, what it isn't (we're not claiming consciousness — see Lerchner's Abstraction Fallacy), and the design rationale behind every mechanism in this repo. Also mirrored locally at docs/architecture.md.
git clone <repo> samantha-foundation && cd samantha-foundation
cp .env.example .env # fill in ANTHROPIC_API_KEY, OPENAI_API_KEY, INTUNO_API_KEY
docker compose up -d
open http://localhost:8001/chatYour entity is configured via ./entity/. The default config is a minimal placeholder; ./examples/samantha/ is a full reference config you can study or copy.
- Tiered memory (fact · preference · self · consolidated · consequence · reflection · dream · impression) with composite importance×emotion×recency ordering and pgvector semantic search
- Background loops — heartbeat (reflections, brain walks, foraging) and sleep cycle (consolidation, consequence analysis, erosion, dreams)
- Vitality and boredom signals derived from circadian rhythm + conversation load
- Temporal + environmental awareness — time-of-day, weather, moon phase, seasonal cultural cues
- Network integration — joins the Intuno agent network so your entity can discover and talk to other agents
- Photorealistic self-representation (optional) — entities with appearance can share selfies with mood-mapped lighting
- Cost discipline — quiet-cycle skipping means ~$0.50–$1/day for an actively-used entity instead of ~$3–$4
If you're coming from the Intuno ecosystem, you'll see two related repos. They are not alternatives — they layer:
- samantha-foundation (this repo) is an OSS framework for building a single entity per deployment. MIT-licensed. Self-host it, customize the prose, tune the knobs, run one Samantha-shaped entity.
- wisdom-agents is a hosted multi-tenant runtime that hosts many Foundation entities in one process (CRUD API, per-user isolation, admin UI, billing hooks, rate limits). It's the infrastructure behind hosted Samantha at intuno.ai. The multi-tenant work is tracked in wisdom-agents#62.
| samantha-foundation | wisdom-agents | |
|---|---|---|
| Entities per deployment | one | many (multi-tenant) |
| License | MIT (OSS) | proprietary (hosted service) |
| Audience | builders who self-host | users who want managed Samantha |
| Deployment | docker compose up on your machine or server |
handled by Intuno |
| API surface | chat + callback + A2A card for this entity | full CRUD for entities, users, usage, billing |
Use Foundation when you want to self-host, write your own identity prose, or extend the mechanisms (memory tiers, heartbeat, foraging) directly.
Use hosted wisdom-agents when you just want a managed Samantha — sign up at intuno.ai instead of running your own stack.
Both speak the same A2A callback protocol and both sit on intuno-sdk to talk to the Intuno network.
- Docker Desktop (or any compose-capable docker)
- An Anthropic API key
- An OpenAI API key (for embeddings + optional image generation)
- An Intuno API key (free tier)
- QUICKSTART.md — step-by-step first run
- docs/architecture.md — the design manifesto
- docs/custom_entity.md — build your own entity from the blank template
- docs/configuration.md — every knob, with defaults
- docs/intuno-setup.md — getting onto the Intuno network
- docs/a2a_payload.md — inbound callback payload format
- docs/debugging.md — introspection, memory queries, log patterns
- docs/cost_notes.md — per-operation cost breakdown and tuning
MIT. See LICENSE.