Skip to content
Projects

spearsheep/anima-brain has 53 GitHub stars and 8 forks. GitHot measured +19 stars in 24 hours. Last checked 2026-11-17 02:58 UTC. Last push 2026-11-13.

How these counts are measured

53 stars8 Forks +19 in 24h

Measured star growth

in 24h
+19
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Local-first memory and emotional continuity for AI companions. Python SDK, MCP integrations, and an optional web showcase.

Web & Apps

README.md

Original

Anima Lab

Anima Brain

English   |   简体中文

Memory and emotional continuity for AI companions.

Python 3.11+   ·   Alpha 0.6.0   ·   MIT-licensed code

Quickstart   /   SDK   /   Agent integrations   /   Docs   /   Try Anima

A developer toolkit for building agents with persistent memory, character identity and emotional continuity. Use it from Python, plug it into an existing agent through MCP, or connect your own frontend. Bring your own model. An optional Companion Studio web example lets you explore the SDK interactively.

The public project is Anima Brain. The Python distribution remains companion-engine, imports use companion_engine, and the CLI is companion, preserving existing integrations.

This project adapts the memory and brain architecture behind Anima Lab into a standalone Python implementation. It carries over selected designs and logic, with local storage, configurable providers and developer-facing APIs. It is a separate adaptation with different defaults and capability coverage, not the complete Anima app backend or a promise of identical behavior. See what was adapted.

What it gives your agent

Capability In this SDK
Grounded memory Original messages, source-backed facts, corrections, contextual notes and linked evidence.
Retrieval and continuity Local lexical search, optional embeddings, bounded follow-up lookup, cited core and episode summaries.
Character and response guidance Persona, expression preferences, emotional-attunement records and optional fictional relationship state.
Multimodal operations Vision observations, image generation and reference edits, speech and transcription through separately configured providers.
Live calls Streaming Doubao ASR + the same brain + character speech; optional Vidu S2 animated video over managed RTC.
Application control Typed results, memory review, context budgets, usage receipts and request replay.

The engine runs locally with SQLite + FTS5. It requires no Anima account or Convex backend. The Python package stays headless. The optional web showcase is a separate React application in examples/showcase/, with character chat, memory editing and context inspection. Optional MCP cards expose memory controls and voice playback inside compatible hosts.

Quickstart

With Python 3.11+ and SQLite FTS5, clone the repository and run the offline example:

git clone https://github.com/spearsheep/anima-brain.git
cd anima-brain
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python examples/offline_demo.py

The offline example uses synthetic data and makes no model calls. To chat with a real provider, configure a Chat Completions-compatible model supporting JSON-object output:

export COMPANION_BASE_URL='https://your-provider.example/v1'
export COMPANION_MODEL='your-model-id'
# Bash: enter the key without putting its value in shell history.
read -s -p 'API key: ' COMPANION_API_KEY
export COMPANION_API_KEY
python examples/chat.py

Provider calls use your account. No provider or model is selected implicitly. The terminal example retrieves memory without extra planning calls by default; python examples/chat.py --help lists optional lookup, history and memory controls.

Optional web showcase

Companion Studio: Anima-style local companion interface

A responsive local studio with Anima’s paper-and-ink design, character portraits and subtle motion. It uses the real engine for chat, memory, review and source inspection.

python -m pip install -e '.[http,calls]'
npm ci --prefix examples/showcase
npm run build --prefix examples/showcase
python examples/showcase/serve.py --open

Configure your model in the studio, or add --demo for a clearly labeled offline preview. See setup, capabilities and storage. This is a local, single-owner example with live voice and animated video calls. Public multi-user hosting requires your own authentication and deployment layer.

Inside the brain

One turn through memory, response and emotional continuity

Static diagram · Explore the Brain Atlas: semantic vs episodic memory, the cited consolidation cycle, retrieval formulas and emotional continuity. Four animated views follow the implemented Python paths. Start the showcase and open ?view=architecture to play or step through them, adjust recency/importance inputs, and explore PAD vs tension decay. RRF relevance and time-aware follow-up priority are shown separately. The page supports reduced motion, makes no model calls and reads no private conversations. Use English / 简体中文 in the atlas header to switch languages. The Chinese README embeds its own Chinese animation and static diagram; both versions share the same graph layout and calculations.

Live calls use this same path. The SDK exposes brain.call(character_id, CallOptions(...)) with streaming audio, transcripts, interrupt/mute controls and saved delivery receipts. See provider setup, SDK example and lifecycle.

Python SDK

With your provider configured:

import asyncio
from companion_engine import CompanionBrain, Settings

async def main():
    async with CompanionBrain(
        storage="./output/brain.sqlite3",
        user_id="alice",
        settings=Settings.from_env(),
    ) as brain:
        if not any(c.id == "mika" for c in brain.characters()):
            brain.create_character(
                character_id="mika",
                name="Mika",
                persona="Direct, playful, caring without empty reassurance.",
            )

        reply = await brain.chat(
            "mika", "Please remember I prefer tea.", request_id="message-1",
        )
        print(reply.text)
        print(reply.memory_ids)

asyncio.run(main())

Reopen the same database and user ID to continue. Use a stable request ID for retries and a new ID for each new message. Synchronous applications can use chat_sync().

Settings selects providers and model limits. BrainConfig controls memory retrieval, recent history, context budgets and response instructions. Character settings control memory writes and relationship behavior. Creating a character makes no model or image-generation call; optional SDK embedding and summary jobs start off.

→ SDK guide · Memory, vision and media arguments

How it works

Your app or agent host
        │
        ▼
  Prepare context ─── character + recent conversation + retrieved evidence
        │
        ▼
  Generate reply ──── SDK calls your model, or the MCP host writes the reply
        │
        ▼
  Validate & commit ─ original messages + grounded proposals + optional state
        │
        ▼
  Local SQLite ────── available to the next conversation

Memory writes can be automatic, reviewed or off. Disabling fact writes still stores conversation history; reading, writing and retention are separate concerns. Quote validation checks provenance, not the truth of every model interpretation.

The Python adaptation shares Anima's emphasis on memory and continuity. It includes optional voice-call and animated-video adapters, but does not include Anima's full consumer application, hosted infrastructure, billing or autonomous outreach. Architecture and implementation boundaries.

Connect your agent

For Claude Code, Claude Desktop and DeepSeek Harness:

python -m pip install -e '.[mcp]'
companion --db ./output/host/brain.sqlite3 host-package ./output/hosts

Follow the generated START-HERE.md. It contains paths for your checkout, so generate it on the machine where the engine will run. The host uses its own reply model.

MCP makes tools available; the host must call them to retrieve context and save turns. It does not automatically capture every conversation. See host integrations and connection modes, including ChatGPT.

For programmatic loopback HTTP/MCP, install .[http] and run companion http. A separate companion settings command opens only a private provider-configuration form when needed. Neither starts a chat application.

Try Anima

Want a ready-to-use companion instead of building an integration? Use Anima Lab:

Website & web app · iPhone / iPad · Android download

Rina, an Anima Lab companion, at an aquarium   Sean, an Anima Lab companion

Rina and Sean from Anima Lab's public website. These images show the consumer product's characters, not preinstalled SDK characters or features. Android is distributed as a direct APK through the official download page.

Documentation

Start here For
SDK guide Chat, configuration, memory review and recovery
SDK capabilities Memory limits, vision, images, speech and transcription
Host integrations Claude and DeepSeek Harness setup
Feature reference MCP tools, CLI and lower-level APIs
Architecture Anima adaptation, retrieval, persistence and limits
Memory maintenance Optional indexing and summary work
Contributing Development, testing and release checks

Full documentation index · Verification · Changelog

Status and license

Alpha, installed from source. Protocol and persistence tests are separate from real-model quality evaluation. Emotional state is fictional simulation, not a psychological assessment. Local storage does not mean local inference: configured providers receive submitted context. Owner IDs are namespaces, not authentication. Read Security before deployment.

Code is MIT licensed. Anima branding and character artwork have separate asset terms; they are not runtime dependencies.