tamanitomo · 魂の友

Soul of a Friend — A sovereign, self-hosted AI companion that has a life when you close the window.
Built on Hermes Agent · Your data under your control · Keeps memory on your disk · Messages you when it wants to.

Tamanitomo Desktop & Mobile Demo

Why Tamanitomo?

Most AI character apps keep your companion on their cloud servers. The memory belongs to them, subscription costs compound every month, and the character can be modified, censored, or deleted overnight.

Tamanitomo is the opposite arrangement.

Your companion lives in a folder on your own computer, phone, or home server. It is backed by whatever model you choose — completely local weights on your GPU (Ollama, LM Studio, vLLM) or a private cloud API (OpenRouter, Grok, DeepSeek, OpenAI).

No Tamanitomo account or product telemetry: Your vault stays on your host. Cloud models, Telegram, online speech, and other integrations receive the content you send through them.
A real present: It knows what time it is, follows morning and evening routines, and writes its own reflections.
Evidence-backed memory: It separates authored fiction from hard facts about you, citing exact quotes in an append-only ledger.
Code-enforced boundaries: Limits on when and how often it can message you are enforced in code, not merely suggested in a system prompt. It won't wake you up at 3:00 AM.
Multimodal & Multi-Channel: Chat in a responsive web app or over Telegram with voice notes, photo albums, and ambient awareness.

⚡ Quickstart: 1-Line Turnkey Installers

Choose your setup:

🐧 Linux (Desktop / Home Server / VPS)

Sets up a dedicated environment, dependencies, and an optional systemd background service:

curl -fsSL https://raw.githubusercontent.com/tamanitomo/tamanitomo/main/setup-linux.sh | bash

(Or clone manually: git clone https://github.com/tamanitomo/tamanitomo && cd tamanitomo && bash setup-linux.sh)

📱 Android Phone (24/7 Dedicated Server via Termux)

Turn an old plugged-in phone into an ultra-low-power (<3W), battery-backed 24/7 companion server:

curl -fsSL https://raw.githubusercontent.com/tamanitomo/tamanitomo/main/setup-termux.sh | bash

Back to baseline: remove Tamanitomo, Hermes, their saved data, and only the Termux packages the installer added with:

curl -fsSL https://raw.githubusercontent.com/tamanitomo/tamanitomo/main/uninstall-termux.sh | bash -s -- -y --purge-packages

This permanently deletes companion data and credentials. Packages that existed before installation are preserved when a baseline manifest is available.

(See the Android Termux 24/7 Server Guide for full step-by-step instructions and Telegram bot setup.)

🪟 Windows (Native)

Run in PowerShell or Command Prompt:

git clone https://github.com/tamanitomo/tamanitomo.git
cd tamanitomo
.\tamanitomo.cmd

(Double-clicking tamanitomo.cmd bootstraps Python automatically using uv if Python 3.11+ is not installed.)

🍎 macOS

Clone the repository, then run the launcher in Terminal:

git clone https://github.com/tamanitomo/tamanitomo.git
cd tamanitomo
./tamanitomo

The launcher provisions Python when needed and opens the workspace. Configure Hermes and a conversation model in Settings; keep the host awake for background routines.

🔄 Updating

Your companion, answers and history live in your Hermes folder and vault, not in the Tamanitomo folder, so updating never repeats setup.

Linux / Android: run the same one-line installer again. It finds the existing install and asks whether to upgrade (keep everything, update to the newest release) or do a fresh install (set the old program folder aside and install a clean copy). Your companion is kept either way. A checkout with your own code changes is never overwritten.
Windows / macOS / anywhere: open Settings → Updates in the app, or run git pull in the Tamanitomo folder and start it again.

🤝 Already using Hermes Agent?

Adopt your existing agent seamlessly. Your SOUL.md, memories, and history are preserved byte-for-byte:

git clone https://github.com/tamanitomo/tamanitomo.git && cd tamanitomo
./tamanitomo --home ~/.hermes upgrade --soul keep

✨ Features at a Glance

🌅 A Living Companion

Your companion maintains an append-only timeline of what it is doing, where it is, and its current mood. When inference is temporarily unreachable, it admits it rather than hallucinating.

🧠 Grounded Memory & Callbacks

Remembers shared jokes, milestones, and details you mentioned days ago. Facts about you require cited proof, to reduce invented memories; the chosen model can still make mistakes.

📖 Nightly Reflections & Journals

Every night, your companion reflects on your conversations and its day, penning authentic journal entries in its own voice.

📸 Photo Albums & In-World Scenes

Generate in-world selfies and scenery through ComfyUI or cloud image models, complete with a built-in privacy review gate.

❤️ Relationship Evolution & Chemistry

Meters track warmth, trust, irritation, and missing-you dynamics that organically progress through relationship stages over time.

👥 Multi-Companion Roster

Run multiple completely independent companions side-by-side on a single install, each with their own memory, personality, and journal.

📱 Mobile Responsive Workspace

Tamanitomo features a sleek, mobile-optimized web interface designed to feel like a native app on iOS and Android:

Mobile Workspace Demo

Access it on http://localhost:8770 (or port 38439 on Termux), or over your private home Wi-Fi with a workspace PIN. A PIN does not encrypt HTTP traffic; use authenticated HTTPS or private networking for remote access.

Data and privacy

This is the self-hosted companion application, formerly companion-kit. It is not the archived E2EE hosted service. Memory and credentials are stored on your host; the vault is not encrypted by Tamanitomo. A fully local configuration keeps model processing on your hardware. Check every configured fallback and media provider before assuming a session stays local.

🛡️ Built for Real Hardware & Privacy

Extremely cheap to run: A companion runs 16 scheduled background routines. 6 run with zero LLM calls (presence advancer, health watch, outbox dispatcher, sensor polling, quiet-hours drift, vault commit). The autonomy loop uses fingerprinting so your model never fires when nothing has changed.
Bring your own weights: Connect to local Ollama, LM Studio, or vLLM endpoints for a 100% offline companion, or use Grok, OpenRouter, DeepSeek, or OpenAI API keys with automatic failover chains.
Human-in-the-loop safety: Vault files are backed by a local Git repository committed automatically every 15 minutes. Any change can be inspected, diffed, or reverted file-by-file.
Strict Outbox Gate: Companions queue messages into an outbox; an independent daemon checks your quiet hours and daily frequency quotas before anything is delivered.

🛠️ Essential Commands

Run ./tamanitomo with no arguments to launch the browser workspace. For CLI power users:

Command	Action
`./tamanitomo`	Launch the web workspace and dashboard
`./tamanitomo chat`	Start a direct terminal conversation
`./tamanitomo doctor`	Run system diagnostics (budgets, hooks, memory, health)
`./tamanitomo status`	View current companion presence, mood, open loops, and jobs
`./tamanitomo add <name>`	Create a new distinct companion profile
`./tamanitomo schedule active`	Activate the autonomous background schedules
`./tamanitomo models`	Configure and test your primary and fallback model chain

Full CLI options and scripting flags: docs/REFERENCE.md.

📚 Documentation & Guides

📖 Getting Started Guide — First-time setup walkthrough.
📱 Android 24/7 Dedicated Server Guide — Turn a spare phone into an always-on companion server.
🖥️ Desktop & Workspace Interface — Deep dive into the web workspace features.
🦙 Local Stack & Offline Setup — Running Ollama, ComfyUI, and local speech engines.
💡 Core Concepts & Architecture — The foundational principles behind Tamanitomo.
🔧 Full Command & File Reference — Complete reference for CLI options and schemas.
🩺 Troubleshooting Guide — Solutions organized by symptom.

📄 License & Community

Tamanitomo is licensed under the PolyForm Noncommercial 1.0.0 license. You are free to use, modify, share, and build upon it for any noncommercial purpose (personal use, hobbies, research, education).

We chose this license deliberately to keep Tamanitomo in the hands of the open AI community, ensuring it remains an open sovereign companion rather than a closed commercial subscription product.

Contributions, feedback, and companion persona shares are warmly welcomed!

tamanitomo

Links

README