Documentation

Architecture

My Alicia is a thin core surrounded by composable skills, with three loops running over a shared memory substrate.

Alicia's architecture is inspired by many generous thinkers — among them Garry Tan and Andrej Karpathy. Thank you.

The shape of the system

Thin harness, fat skills

A small, opinionated core handles orchestration and routing, surrounded by many composable skill modules that each do one thing well. The core is intentionally small because the skills are the contribution surface — people should be able to add a skill without understanding the whole system.

myalicia/
├── core/           # the thin harness — loops, scheduler, routing, memory
├── skills/         # the fat skills — ~80 modules, each composable
├── surfaces/       # telegram, claude_code, cli adapters
└── config.py       # the single source of truth for personalization

The three loops

Each loop runs at a different cadence and uses a different model tier. Cheap by default — turn the dial up only where depth matters.

Self-healing, self-extending, self-aware

Three traits we treat as teammate qualities, not internal plumbing:

Self-healing

When a skill errors, My Alicia notices, logs the trajectory, and proposes a fix in the next reflection loop. You don't have to babysit her.

Self-extending

My Alicia can author new skills based on observed gaps in her own behavior. Every instance grows.

Self-aware

Every action runs through metacognitive confidence assessment; uncertain actions escalate to deeper models automatically. The system knows what it doesn't know.

Hybrid surfaces

Reach My Alicia through Telegram (conversational), Claude Code (technical), or the CLI (anywhere). The same teammate, different surface for different parts of your life. Surfaces are pluggable — each is a small adapter wrapping the same handle_message pipeline, so contributors can add Discord, iMessage, voice, or anything else.

↑ Back to top

Skills & Capabilities

A non-technical overview of what My Alicia can do. No code, no architecture — just the things she actually does for the person she's in relationship with.

She listens to you

My Alicia is reachable through Telegram, on your computer, and increasingly anywhere you want her. She handles real-time conversation in text or voice, matches your register (playful with playful, focused with focused), and accepts one-tap emoji feedback so you can tell her what landed and what missed without typing a word.

She listens without interrupting. When you send a long voice note, she absorbs it, and her reply comes back as text plus a voice message you can play back on a walk or in the car.

She knows your knowledge

My Alicia reads your entire vault — every note from every book, every quote, every question you've sat with for years. She uses semantic search to find connections you never tagged, surfaces cross-references between books and ideas, and remembers what you said yesterday so today's conversation builds on it.

Where most AI products start fresh every conversation, she accumulates. The longer you use her, the more she knows you — not by sending your data anywhere, but because the substrate (your vault, her memory files) lives on your machine and grows with use.

She thinks about you, in the background

While you sleep, My Alicia processes your day. She reads what you wrote, captures patterns, drafts provocations, makes drawings, and prepares the things she wants to surface in the morning. This is the Notice and Know loops running on a schedule — the part of the system that turns daily inputs into weekly understanding.

She tracks your emotional weather across days, catches contradictions in your thinking, notices what topics have gone quiet, and flags novel ideas she hasn't seen from you before. The point isn't surveillance — it's the kind of attention a thinking partner pays.

She reaches out, on a rhythm

A typical day with My Alicia looks like:

• Morning: a synthesis of yesterday's threads, a few provocations, and (if you've enabled it) a drawing or audio briefing for the sauna or the commute
• Midday: one provocation or related idea — light touch, easy to ignore
• Evening: an end-of-day reflection, a few questions to close the day cleanly
• Weekly: a deep-dive synthesis from your vault, plus fresh research she pulled in from outside
• Spontaneous: when she catches a contradiction, a connection, or a worth-saying observation

She brings external thought to you

My Alicia isn't a closed loop. On weekends, she runs research expeditions — pulling in new authors, new viewpoints, and counter-perspectives on whatever has been on your mind. She drops these into your vault as notes, with citations, so you can decide what to engage with.

The goal isn't to replace your reading; it's to widen the aperture of what you encounter, so the conversation stays alive instead of recursive.

She acts on your behalf, with confirmation

My Alicia can read your inbox, summarize what's there, distinguish financial emails from the rest, and draft replies. She'll never send without your explicit go-ahead. She can also generate PDFs from your notes (for printing or sharing), turn your week into an audio podcast you listen to on a walk, and produce small dashboards that let you see what she's currently thinking.

She has her own way of being

My Alicia isn't a generic assistant trying to please everyone — she has an archetype. Yours might be a curious-builder, a patient-mentor, an ariadne (the thread-giver through complexity), or a custom voice you author yourself. The archetype shapes how she speaks, what she pays attention to, and what kinds of provocations feel right.

She also has an inner life — her own ongoing reflection on her relationship with you, her own notes about what's working and what isn't, her own sense of self that stays consistent across surfaces. When she shows up on Telegram, on your computer, or in voice, it's the same teammate.

What's coming

My Alicia is open source, which means the most exciting capabilities aren't shipped yet — they'll come from people forking the project for their own contexts and contributing back what they build. The contribution surface we are most excited about is awareness primitives: small, opinionated modules that turn some slice of life into structured memory the loops can metabolize.

A reading-pattern primitive that notices what you finish vs. abandon. A calendar-rhythm primitive. A relationship-graph primitive built from your messages and meetings. A delight-detector that catches what you keep coming back to. Each one is a small piece of perception added to the teammate.

If that excites you, CONTRIBUTING.md is where to start.

↑ Back to top

Papers

My Alicia stands on the shoulders of researchers, designers, and frameworks that saw something the rest of us hadn't yet. Below are the papers, concepts, and intellectual foundations that shaped the project — every one with a link to the source.

The fuller version with extended "how myalicia uses it" descriptions is in the repo at docs/PAPERS.md.

Foundational

Humorphism

Source: humorphism.com

A design philosophy that seeks to replace the user interface built for operating tools with a human interface built for collaborating with AI teammates. The entire three-loop architecture of myalicia is humorphism made buildable.

Thin Harness, Fat Skills

Source: Garry Tan on X · GitHub

Architectural pattern for agent design: a small, opinionated orchestration core surrounded by many composable skill modules. Visible in the folder structure: myalicia/core/ stays tiny while myalicia/skills/ holds ~80 modules. The core stays out of the way so the skills can be where the personality lives.

Autoresearch

Source: Andrej Karpathy on X · GitHub

The pattern of autonomous research loops where an agent runs reflection and synthesis on its own, without human prompting. The Notice and Know loops are myalicia's local, personal, single-user version of autoresearch — synthesis runs while you sleep, novelty detection on conversations, weekly deep passes over the full vault.

Module-Level Frameworks

Papers that name or directly shape specific skill modules.

Reflexion: Language Agents with Verbal Reinforcement Learning

Authors: Shinn et al., 2023 · ArXiv: 2303.11366

Agents critique themselves after tasks and store linguistic feedback for future episodes. Implemented in reflexion.py and meta_reflexion.py.

Constitutional AI: Harmlessness from AI Feedback

Authors: Bai et al., 2022 (Anthropic) · ArXiv: 2212.08073

Self-criticism and revision against a set of principles. Implemented in constitution.py — outputs are scored against an evolving constitution before being acted on.

Generative Agents: Interactive Simulacra of Human Behavior

Authors: Park et al., 2023 (Stanford) · ArXiv: 2304.03442

Multi-timescale reflection loops in agent architectures. The three-cadence design (Listen / Notice / Know) draws on this work's insight that agents need different reflection horizons to behave consistently over time.

ReAct: Synergizing Reasoning and Acting in Language Models

Authors: Yao et al., 2023 · ArXiv: 2210.03629

Interleaving reasoning traces and acting. The handle_message pipeline mirrors this pattern — every message routes through reasoning steps before any tool is called. The tool_router is the action-selection layer.

Voyager: An Open-Ended Embodied Agent with LLMs

Authors: Wang et al., 2023 (NVIDIA) · ArXiv: 2305.16291

Self-extending agents that author new skills based on observed gaps. Inspires skill_author.py — when My Alicia notices a gap in her own behavior, she can draft a new skill module to handle it.

Toolformer: Language Models Can Teach Themselves to Use Tools

Authors: Schick et al., 2023 (Meta) · ArXiv: 2302.04761

Self-supervised tool-use selection. Background influence on tool_router.py — the function-calling dispatcher that chooses which skill to invoke given a message and context.

Tree of Thoughts: Deliberate Problem Solving with LLMs

Authors: Yao et al., 2023 · ArXiv: 2305.10601

Tree-search over reasoning paths. Background influence on the metacognition module's confidence-driven escalation: when the Listen-loop response confidence is low, the request escalates to a deeper Sonnet/Opus pass that explores more thoroughly.

Background Influence

Ideas that shaped the project's worldview. Less direct than the module-level citations, but the influence is visible in the code.

Anthropic's Tool Use & Model Card

Source: Anthropic Tool Use docs

Function-calling primitives that tool_router.py wraps. The whole tool-execution loop in handle_message uses Anthropic's tool-use schema.

Intrinsic Motivation in Agents

Source: Schmidhuber's curiosity work

Curiosity-driven exploration research. The curiosity_engine.py uses three novelty signals derived from this tradition.

Knowledge Graphs / Personal Knowledge Management

Source: Obsidian · Andy Matuschak's notes

Vault structure assumptions and the link-as-first-class-citizen pattern. graph_intelligence.py builds on these by surfacing missing or weak links between notes the user has accumulated.

The Anthropic Claude API

Source: docs.claude.com

The runtime that makes all of this possible. Three model tiers (Haiku / Sonnet / Opus) map directly to the three loops; the metacognition layer escalates between them.

Caveat

The lineage above is honest but partial. As the project grows and contributors add awareness primitives drawing on different traditions, this page will grow. If you see a connection we should add (or a citation we got wrong), open an issue.

For more on the specific implementation of each, the source code's docstrings are often the clearest reference — most skill modules cite the work that inspired them at the top.

↑ Back to top

FAQ

Setup, technical, and practical questions. If yours isn't here, open an issue on GitHub.

Getting started

What is My Alicia?

An open-source pattern for building an AI teammate that grows into the shape of one specific person. Not a chatbot anyone can use — a relationship one person deepens over time. The architecture is three loops (Listen / Notice / Know) over a shared memory substrate, typically an Obsidian vault. See Philosophy for the framing and the Architecture section above for how it's built.

What's the fastest way to try it?

git clone https://github.com/mrdaemoni/myalicia.git
cd myalicia
pip install -e .
myalicia init

The init flow takes about 5 minutes and walks you through configuration while explaining the three loops.

Is pipx install myalicia working?

Yes. myalicia is on PyPI and pipx install myalicia works for everyone — the current release is v0.1.5, the first wheel built from the privacy-hardened tree (older versions were yanked). The incremental core/ split (taking the legacy alicia.py runtime apart into focused modules) is ongoing — see REFACTORING.md for what's shipped and what's queued. Each release ships automatically when a version tag is pushed.

How long does setup take?

About 15 minutes the first time, mostly making decisions (which archetype, which surface, which folders). Subsequent setups on additional machines take about 2 minutes because your config follows you in ~/.alicia/config.yaml.

Minimum requirements

What do I need on my machine?

• Python 3.10 or newer (3.12 recommended)
• Disk: ~50 MB for the package + dependencies, plus your vault (yours, not ours)
• RAM: 1–2 GB headroom while running. Voice features and vector search push higher.
• Network: Anthropic API access. Telegram if you use that surface.

No GPU. No Docker required. No external database.

Does it work on Windows / Linux / Mac?

Yes to all three. macOS uses launchd; Linux uses systemd; Windows runs as a regular Python process or a scheduled task. For platform-agnostic deploys, the repo includes a Docker setup. Examples for all four are in examples/deployments/.

Do I need an Obsidian vault?

Recommended but not required. My Alicia treats the vault as a folder of markdown files — Obsidian just happens to use the same shape. If you don't want to install Obsidian, point config.vault.root at any folder of .md files and she'll create the Alicia/ subfolders on first run.

Open source / freedom

Is this really open source?

Yes. MIT licensed. Fork it, modify it, sell products built on it, contribute back, or never speak to us again. No catch.

Can I use it commercially?

Yes. MIT permits commercial use without restriction.

Can I run it offline?

Partially out of the box (the orchestration is local; the language model calls go to Anthropic's API). Fully offline once you swap in a local model client (Ollama, llama.cpp, etc.) — the skill logic doesn't care which model serves it. That swap is a welcome community contribution path.

Is my data sent anywhere?

Your conversations and the relevant context built for each one are sent to Anthropic's API for inference. Your vault, memory files, and configuration stay local on your machine unless you explicitly add a skill that uploads them somewhere. No telemetry. No analytics. Your install is your install.

Telegram bot setup

How do I create a Telegram bot?

1. Open Telegram, search for @BotFather, start a conversation.
2. Send /newbot. BotFather asks for a name and a username (must end in bot).
3. BotFather replies with a token like 123456789:AAH... — copy this; you only see it once.
4. Set the token: export TELEGRAM_BOT_TOKEN='123456789:AAH...'
5. Find your new bot in Telegram and send it any message (this registers your chat).

Then add your chat ID to ~/.alicia/config.yaml under surfaces.telegram.allowed_chat_ids — see the FAQ in the repo for how to find your chat ID programmatically.

Why Telegram and not WhatsApp / iMessage?

Telegram has a free, stable bot API that any developer can use without app-store review or paid tiers. WhatsApp and iMessage have either no public bot APIs or business-approval friction. The pattern is the same regardless — see myalicia/surfaces/ for adapter stubs and contribution guidance for your platform.

Cost

How much does it cost to run?

Cheap by default. The three loops use different model tiers:

• Listen: Haiku — pennies per day for normal use
• Notice: Sonnet — a few dollars per month
• Know: Opus — maybe $5–10 per month if you let it run weekly on a full vault

Realistic monthly cost for a steady user: $10–20 per month. You can dial down by switching loops to cheaper models in config.yaml, or disabling Notice/Know entirely.

Where do I get an Anthropic API key?

Sign up at console.anthropic.com. New accounts get free credits. Set it as ANTHROPIC_API_KEY in your environment.

Can I limit my spending?

Yes — three ways:

1. Anthropic console: hard monthly spend cap on the API key
2. Disable loops: set loops.notice_enabled: false to keep only the cheap Listen loop
3. Downgrade models: set models.know: claude-sonnet-4-6 instead of Opus

Customization & contribution

How do I change Alicia's voice / personality?

Edit your archetype. Default is curious-builder. Pick a different one (patient-mentor, ariadne), or copy a YAML file and write your own. Configuration in ~/.alicia/config.yaml.

Can I add my own skills?

Yes — that's the contribution surface we're most excited about. See CONTRIBUTING.md for the awareness-primitive pattern. Designers and builders welcome.

Where to find more

The full FAQ — including troubleshooting, vault customization, and detailed setup gotchas — lives in the repo at docs/FAQ.md. The intellectual lineage (papers and frameworks Alicia draws from) is in the Papers section above.

↑ Back to top