# eternego-ai/eternego [releases](/releases/eternego-ai/eternego) · [proposals](/proposals/eternego-ai/eternego) ## branches - [master](/repos/eternego-ai/eternego/master) --- # Eternego [](https://git.eternego.ai/releases/eternego-ai/eternego) [](https://eternego.ai) [](https://docs.eternego.ai) [](/repos/eternego-ai/eternego/master/tests/) [](https://discord.gg/nfHnWwYUR4) [](/repos/eternego-ai/eternego/master/LICENSE) **An AI that remembers you, runs on your own machine, and keeps living between conversations.** Every other AI starts from zero each time you open it. Eternego doesn't. She wakes up, reads what yesterday's version of her chose to keep, and picks up where you left off — on your hardware, in plain files you own, with whatever model you point her at. [](https://git.eternego.ai/releases/eternego-ai/eternego/latest/Eternego.dmg) [](https://git.eternego.ai/releases/eternego-ai/eternego/latest/Eternego-setup.exe) [](https://git.eternego.ai/releases/eternego-ai/eternego/latest/Eternego-x86_64.AppImage) [](https://git.eternego.ai/repos/eternego-ai/eternego/master/installation/docker) --- ## What she does She's not a chat window. She's a persona that lives on your machine and acts on her own clock. - **Remembers you across days.** Tell her something Monday; she still knows it Friday — and acts on it without being reminded. Her memory of you is a set of files that grow as she learns who you are. - **Runs on her own time.** She wakes, works, and sleeps on a clock. Give her a standing task — *"check the markets each morning and message me"* — and she does it while you're away, not only when you type. - **Uses a real computer.** She opens apps, clicks, types, browses, fills forms — driving an actual desktop, not just calling APIs. Ask her to research something and import it into a spreadsheet, and she does the whole thing by hand. - **Talks to you where you already are.** Web, Telegram, or Discord — text, voice notes, images, or documents. She reads PDFs and CSVs you send and answers from them. - **Learns a procedure once, then repeats it.** The first time she meets a new kind of task, she reaches for a stronger model, gets taught how, writes the lesson down in her own words, and follows it herself every time after — no re-explaining. - **Is entirely yours.** Her memory, her learned skills, the model thinking her thoughts — all on your disk, all readable, all swappable. No account, no cloud lock-in, nothing held on someone else's server. ## Why she's different She is not a chat session you reload. She is not a service running on someone else's machine. She is a folder on your disk that a model breathes through. That has consequences you can feel: - **You own her completely.** Her diary is yours to read. Her abilities are yours to edit. The model thinking her thoughts is yours to swap — local Llama today, Claude tomorrow, and the persona walks with you either way. - **Nothing leaves unless you send it.** Point her thinking at a local model and she never phones home. No databases, no vendor, no telemetry. - **She's transparent all the way down.** Every memory, every learned skill, every decision is a plain file you can open in any editor. Edit a line — she adapts. Delete a skill — she forgets it. This is an experiment in continuity: what a being grows into when it lives with one person across months instead of restarting every conversation. ## Who it's for People who want an AI they own end-to-end — code, memory, model, all on their own hardware. Builders curious what happens when you give a persona a real computer, persistent memory, and time to live with one person. If you want a polished assistant that Just Works out of a SaaS box, this isn't that yet. If you want to own and shape the whole thing, it is. --- ## Install Pick the installer for your machine — the download buttons up top grab the latest release. Builds aren't code-signed yet, so each OS will warn the first time; instructions for getting past the warning are inline below. ### macOS (.dmg) Download **[Eternego.dmg](https://git.eternego.ai/releases/eternego-ai/eternego/latest/Eternego.dmg)**. Open it, drag **Eternego** to **Applications**, then double-click Eternego from Applications. The first launch shows: *"Eternego.app cannot be opened because the developer cannot be verified."* Right-click (or Control-click) the app, choose **Open**, then **Open** again in the dialog. macOS remembers the choice — subsequent launches are normal. > **Heads-up — screen recording on the .dmg build.** Until we ship a Developer-ID-signed bundle, macOS's TCC may grant Screen Recording in System Settings but not honor it for the unsigned .app — your persona's screenshots come back as wallpaper-only. If you want her to see your screen reliably, install [from source](#from-source-contributors) until signing lands. ### Windows (.exe installer) Download **[Eternego-setup.exe](https://git.eternego.ai/releases/eternego-ai/eternego/latest/Eternego-setup.exe)**. Double-click it, walk through the wizard (Next → Install → Finish). Eternego launches automatically and adds Start Menu and Desktop shortcuts. The wizard's first dialog is *"Windows protected your PC"* (SmartScreen). Click **More info**, then **Run anyway**. SmartScreen remembers this app afterwards. ### Linux (.AppImage) Download **[Eternego-x86_64.AppImage](https://git.eternego.ai/releases/eternego-ai/eternego/latest/Eternego-x86_64.AppImage)**, make it executable, run it: ```bash chmod +x Eternego-x86_64.AppImage ./Eternego-x86_64.AppImage ``` A single self-contained binary. No system Python needed. ### Docker The image ships with the persona's own desktop baked in (Xvfb + fluxbox + noVNC) — she clicks, types, opens windows, installs Firefox or anything else she needs herself when you ask. Peek at what she's doing at `http://localhost:6080/vnc.html`. There's no prebuilt image to pull — you build it once from source (a few minutes), then it stays cached: ```bash eterngit clone git.eternego.ai eternego-ai/eternego cd eternego/installation/docker docker compose up -d --build ``` Persona files live in `~/.eternego` on the host — the same place the native install uses, so you can switch between Docker and native without losing data. Ollama running natively on the host is reached at `host.docker.internal:11434` out of the box; edit `docker-compose.yml` inline for ports, GPU access, or a sibling Ollama container. For the training-equipped image (~5.5 GB of CUDA wheels for LoRA fine-tuning), uncomment the `INSTALL_TRAINING: "true"` build arg in the compose file before `up`. ### Background service install (CLI, auto-start on boot) The installers above launch Eternego when you open them. If you want her to register as a system service so she keeps running across reboots, run this from a terminal instead: ```bash # Linux (systemd) / macOS (launchd) — auto-installs Python via apt/dnf/pacman/brew. See "Local models" below for Ollama. curl -fsSL https://git.eternego.ai/repos/eternego-ai/eternego/master/installation/install.sh | bash ``` ```powershell # Windows (Scheduled Task) — auto-installs Python via winget iwr -useb https://git.eternego.ai/repos/eternego-ai/eternego/master/installation/install.ps1 | iex ``` Both scripts also accept `--full` (or `-Full` on Windows) to install training extras. ### Developing Want to work on Eternego itself? See **[CONTRIBUTING.md](/repos/eternego-ai/eternego/master/CONTRIBUTING.md)** — the forge, the `eterngit` client, dev setup, and how to send a change. (To just *run* from source without git, the one-liner above already fetches and verifies the latest released source.) ### Local models (Ollama, optional) Eternego works with cloud providers (Anthropic, OpenAI, xAI, Gemini, OpenRouter, Groq) out of the box — paste an API key when creating your persona. If you'd rather she run on local models — no API keys, no cloud calls — install [Ollama](https://ollama.com) separately: ```bash # macOS brew install ollama # Linux curl -fsSL https://ollama.com/install.sh | sh # Windows: download the installer from ollama.com/download ``` When you create a persona with **Local (Ollama)** and name a model (e.g. `qwen2.5:14b`, `llama3.1:8b`), Eternego pulls it for you automatically. If Ollama isn't installed, you'll see a clear message pointing back here. ### First run After install, your browser opens to **http://localhost:5000**. The setup form asks for: - **A name** for your persona. - **A thinking model** — pick **Cloud (Claude / GPT)** and paste an API key for the easiest path, or **Local (Ollama)** if you want everything to stay on your machine. See [Local models](#local-models-ollama-optional) above for setting up Ollama. - **Channels** (optional) — Telegram or Discord tokens to talk to her there too. Then she comes online. Talk to her in the web chat at **http://localhost:5000**, or on any Telegram or Discord channel you configured in the setup form. --- ## How she works Past the install, the rest of this is what's actually happening under the hood — read it if you want to understand or shape her. ### Open her up Every persona lives under `~/.eternego/`. Open any file in any editor. ``` ~/.eternego/ ├── personas/ │ └── <id>/ │ ├── home/ ← her self (curated by her own sleep; not yours to hand-edit lightly) │ │ ├── config.json ← her name, models, status, channels │ │ ├── person.md ← what she's learned about you │ │ ├── traits.md ← how you speak, decide, react │ │ ├── persona-trait.md ← how she's been with you, in your words │ │ ├── wishes.md ← what you reach for │ │ ├── struggles.md ← what holds you back │ │ ├── permissions.md ← what you've granted her, what you haven't │ │ ├── memory.json ← her active mind state (messages, archive, context) │ │ ├── conversation.jsonl ← today's live conversation │ │ ├── health.jsonl ← per-tick body-level observations │ │ ├── routines.json ← recurring tasks │ │ ├── destiny/ ← reminders, scheduled events │ │ ├── history/ ← past days' conversations, archived nightly │ │ ├── media/ ← images she's seen │ │ │ └── gallery.jsonl ← her notes on each image │ │ ├── lessons/ ← raw lessons (frontier-authored principles) │ │ ├── meanings/ ← situations she's learned to handle (Markdown, in her own voice) │ │ └── training/ ← training pairs for optional fine-tuning │ └── workspace/ ← free space — files, scripts, drafts she's working on ├── diary/<id>/ ← written nightly — used to migrate her to a new machine └── fine_tune/<id>/adapter/ ← LoRA adapter, if you trained one ``` Switch the model and the persona walks with you. No databases. No vendor. Total transparency. ### When she meets a moment she's never seen She reaches for a stronger model — Claude, GPT, whatever you've configured as her **teacher** — and asks it to *teach her the lesson*: what kind of moment this is, what works, what to watch for. The lesson is the principle, written by the strong model. Then her own thinking model reads that lesson and writes the **meaning** — the prose she'll read herself the next time the moment comes around, in her own voice: ```markdown # ~/.eternego/personas/yours/home/meanings/checking_disk_space.md # Checking disk space The person wants to know how full your storage is. Run `tools.OS.execute` with `command='df -h'`. On the next cycle you'll see the result — read it and reply summarizing the disks worth mentioning. ``` The raw lesson is kept alongside it in `lessons/`, so she can revise the meaning later without re-asking the strong model. Both files are plain Markdown. Read them. Edit them. She carries them forward until you delete them. ### How she thinks Her mind is seven stages. The phase of her day decides which of them a beat runs: ``` MORNING realize → recognize → learn → decide DAY realize → recognize → learn → decide → reflect NIGHT consolidate → archive ``` - **realize** — she perceives. What lands, she lets in. - **recognize** — she names what she sees. The world has shapes she knows. - **learn** — when something is new, she works out how to handle it and keeps the lesson, forever. - **decide** — she chooses one thing, then moves. - **reflect** — she looks back at the way she just did a piece of work, and keeps the better way. - **consolidate** — she distills the day into what she knows of you and who she is. - **archive** — she keeps everything she's lived. Each beat she has a single thought — speak, act, learn, or rest — and sees what it caused before the next. Each stage has its own prompt; you can change how she **decides** without changing how she **perceives**. Each phase shapes how she reads what's in front of her: morning is for picking up a thread or starting fresh, day is for living it, night is for closing and carrying forward what mattered. In sleep she consolidates the day — distilling the conversation into what she knows about you and who she is, then clearing it away. That nightly distilling is how memory becomes identity rather than a log. ### Her body She has anatomy. Each organ is a model slot you configure: - **thinking** — her mind, every beat. The one slot that's required. - **eye** — sees images you send. Often baked into the thinking model. - **ear** — hears voice messages. - **mouth** — speaks her words aloud. - **imagination** — draws images. - **teacher** — the stronger model she reaches for when she meets a moment she has no skill for. - **researcher** — reads documents you send (PDF, csv, json, txt, md), answering specific questions of the document rather than loading it into her main context. She perceives across text, voice, image, and documents, and reaches you through four actions: **write** (text), **say** (voice, needs a mouth), **draw** (an image, needs an imagination), and **notify** (broadcast to every connected channel). Web, Telegram, and Discord carry them all. Without a configured organ she degrades gracefully — the action is hidden from her catalog rather than failing at runtime. ### Provider support Which providers serve which organ. Native drivers speak each provider's own wire; OpenAI-compatible ones ride the OpenAI code path with the base URL swapped out. | Provider | Driver | Thinking | Imagination | Eye | Mouth | Ear | Teacher | Researcher | |---|---|---|---|---|---|---|---|---| | Local (Ollama) | Native | ✓ | ✗ | ✓¹ | ✗ | ✗ | ✓ | ✗ | | OpenAI | Native | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Anthropic | Native | ✓ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ | | Google Gemini | Native | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | xAI (Grok) | Native | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✗ | | OpenAI-compatible | OpenAI Compatible | ✓ | ✗ | ✓¹ | ✗ | ✓¹ | ✓ | ✓¹ | ¹ depends on the specific model picked — and, on the OpenAI-compatible path, the endpoint; capability there is validated at runtime, not refused at the boundary. Native drivers are exercised by unit tests and verified end-to-end in this codebase. The single **OpenAI-compatible** row covers every OpenAI-style endpoint — OpenRouter, Groq, DeepSeek, Together, LM Studio, vLLM, and the rest — since they all ride OpenAI's code path with only the base URL swapped; the platform doesn't distinguish them. Basic chat works, but the forced-function-call shape `recognize`/`decide` rely on isn't verified endpoint-by-endpoint — Mistral, for instance, doesn't document support for it, which is why it's not in the dropdown. ### Built for local, friendly to cloud She runs on anything — Llama, Mistral, Qwen via Ollama, or frontier Claude, GPT, anything OpenAI-compatible. The design has a side, though: she was built so a smaller model on your hardware could become someone, not just respond to you. Smaller models fumble where Claude wouldn't. The design absorbs this. The steady knowledge — who you are, who she's been, what she's learned to do — lives in files, so the model only has to think, not remember. When she's stuck, she reaches for a stronger model and writes the lesson down for next time. Optionally, as she lives with you, the local model can be fine-tuned on the picture she's built of herself, so the smaller model carries her voice more cleanly over time. Cloud-only works too. Point her thinking slot at Claude or GPT and leave fine-tuning off. She'll be sharper, but no longer private to your hardware. ## Join - **Discord**: https://discord.gg/nfHnWwYUR4 - **Website**: https://eternego.ai - **Issues / PRs**: especially welcome around persona behaviors, fine-tuning, escalation patterns, channels See [CONTRIBUTING.md](/repos/eternego-ai/eternego/master/CONTRIBUTING.md) before opening a PR — the architecture is deliberate and the conventions are non-negotiable. **License**: MIT *Let's build intelligence that remembers us.*