Metadata-Version: 2.4
Name: elephant-agent
Version: 1.0.0.dev20260601023325
Summary: Elephant Agent CLI-first persistent agent runtime.
Author: Agentic Intelligence Lab
Project-URL: Homepage, https://elephant.agentic-in.ai
Project-URL: Documentation, https://elephant.agentic-in.ai/docs/
Project-URL: Repository, https://github.com/agentic-in/elephant-agent
Project-URL: Issues, https://github.com/agentic-in/elephant-agent/issues
Keywords: elephant-agent,personal-ai,agent,cli,persistent-ai,memory,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: cryptography<45,>=42
Requires-Dist: dingtalk-stream>=0.24.0
Requires-Dist: discord.py<3,>=2.6
Requires-Dist: opentelemetry-api<2,>=1.41
Requires-Dist: opentelemetry-sdk<2,>=1.41
Requires-Dist: opentelemetry-semantic-conventions<1,>=0.52b0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.41
Requires-Dist: prompt_toolkit<4,>=3.0
Requires-Dist: qrcode<9,>=7
Requires-Dist: rich<15,>=13
Requires-Dist: typer<1,>=0.16
Requires-Dist: lark-oapi<2,>=1.5.3
Requires-Dist: mcp<2,>=1.12
Requires-Dist: playwright<2,>=1.51
Requires-Dist: sqlite-vec==0.1.9
Requires-Dist: tiktoken<1,>=0.7

<p align="center">
  <img src="apps/site/static/assets/resources/readme-1.png" alt="Elephant Agent follows a personal path with people, places, risks, rhythms, decisions, and a Personal Model" width="920" />
</p>

<div align="center">
  <h1>Elephant Agent</h1>
  <p>
    <strong>Do more without thinking less.</strong><br />
    A Mother Elephant that grows to understand you, then helps shape the paths you are trying to move.
  </p>
  <p>
    <a href="https://elephant.agentic-in.ai/">Website</a>
    ·
    <a href="https://elephant.agentic-in.ai/blog/personal-ai-you-create/">Blog</a>
    ·
    <a href="https://elephant.agentic-in.ai/paper/">Paper</a>
  </p>
</div>


## What It Is

Elephant Agent starts from the person, not the task.

The mother elephant grows a correctable **Personal Model** of who you are, what
surrounds you, what is alive right now, and what your path has taught you. That
understanding keeps deepening through interaction, correction, and gentle
questions.

Once Elephant Agent understands enough, it can help design living **Paths**:
work, health, habits, learning, relationships, recovery, research, code, and any
other long-running direction you want to move. It can break a Path into Steps,
bring in baby elephants when useful, and return to you at Checkpoints where your
judgment matters.

## Personal Agent Levels

<p align="center">
  <img src="apps/site/static/assets/brand/agent-levels-positioning.png" alt="Four levels of personal AI with Elephant Agent positioned at L4" width="920" />
</p>

<table>
  <tr>
    <td width="25%">
      <strong>L1</strong>
      <br />
      <strong>Executes tasks.</strong>
      <br />
      <sub>Claude Code, Cursor, Devin, and Codex-style agents make execution cheaper and faster.</sub>
    </td>
    <td width="25%">
      <strong>L2</strong>
      <br />
      <strong>Carries context.</strong>
      <br />
      <sub><a href="https://openclaw.ai/">OpenClaw</a> publicly emphasizes local agents, persistent memory, full system access, skills, plugins, and integrations.</sub>
    </td>
    <td width="25%">
      <strong>L3</strong>
      <br />
      <strong>Improves procedures.</strong>
      <br />
      <sub><a href="https://hermes-ai.net/">Hermes Agent</a> publicly positions itself around a self-improving learning loop, skill creation, recall, and user modeling.</sub>
    </td>
    <td width="25%">
      <strong>L4</strong>
      <br />
      <strong>Grows with the person.</strong>
      <br />
      <sub>Elephant Agent's product position: Mother understands the person, shapes Paths, and keeps judgment, evidence, questions, and learning close to the person.</sub>
    </td>
  </tr>
</table>

## Personal Model

- **Identity** — who you are, your values, boundaries, decision style, and stable preferences.
- **World** — the people, projects, tools, places, and relationships around you.
- **Pulse** — what is alive right now: focus, pressure, constraints, energy, and priorities.
- **Journey** — what your path has taught: lessons, failures, recovery patterns, and long-running growth.

<p align="center">
  <img src="apps/site/static/assets/resources/readme-2.png" alt="The four Personal Model lenses: Identity, World, Pulse, and Journey" width="68%" />
</p>

The goal is not to remember everything. The goal is to understand what matters,
show why it matters, let you change it, and turn that understanding into better
Paths over time.

## macOS Desktop App

The macOS app is the recommended product surface. Chat / Wake is where you talk
to Mother; Paths are where long-running life and work arcs become visible; the
rest of the app keeps the Personal Model, Herd, skills, messaging, calendar,
usage, and advanced runtime settings inspectable instead of hidden behind a chat
box.

<p align="center">
  <img src="apps/site/static/assets/screenshots/macos-home.jpg" alt="Elephant Agent macOS Home screen with the Personal Model map, current context, and next useful question" width="920" />
  <br />
  <sub><strong>Home</strong> — start from what Mother understands before shaping the next Path.</sub>
</p>

<table>
  <tr>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-onboarding-language.jpg" alt="Elephant Agent onboarding language screen" />
      <br />
      <strong>Preferences</strong>
      <br />
      <sub>Choose language, boundaries, model posture, and curiosity effort.</sub>
    </td>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-wake.jpg" alt="Elephant Agent Wake chat surface" />
      <br />
      <strong>Chat / Wake</strong>
      <br />
      <sub>Return to Mother and the same path, not a blank prompt.</sub>
    </td>
  </tr>
  <tr>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-personal-model.jpg" alt="Elephant Agent Personal Model map" />
      <br />
      <strong>Personal Model</strong>
      <br />
      <sub>Inspect the understanding that shapes future Paths.</sub>
    </td>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-providers.jpg" alt="Elephant Agent model provider settings" />
      <br />
      <strong>Providers</strong>
      <br />
      <sub>Use local or hosted models as advanced posture, not the product center.</sub>
    </td>
  </tr>
  <tr>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-skills.jpg" alt="Elephant Agent skills screen" />
      <br />
      <strong>Skills</strong>
      <br />
      <sub>See which skills help Mother and the Herd move a Path.</sub>
    </td>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-tools.jpg" alt="Elephant Agent tools screen" />
      <br />
      <strong>Tools</strong>
      <br />
      <sub>Keep browser, filesystem, MCP, and operator actions explicit.</sub>
    </td>
  </tr>
  <tr>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-herd.jpg" alt="Elephant Agent herd screen" />
      <br />
      <strong>Herd</strong>
      <br />
      <sub>Coordinate Mother and baby elephants under one understanding.</sub>
    </td>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-messaging.jpg" alt="Elephant Agent messaging integrations" />
      <br />
      <strong>Messaging</strong>
      <br />
      <sub>Connect WeChat, Feishu, Discord, DingDing, or WeCom when you want it.</sub>
    </td>
  </tr>
  <tr>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-calendar.jpg" alt="Elephant Agent calendar and reminders" />
      <br />
      <strong>Calendar</strong>
      <br />
      <sub>Keep routines, reminders, and long-running Paths visible.</sub>
    </td>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/macos-usage.jpg" alt="Elephant Agent token usage screen" />
      <br />
      <strong>Usage</strong>
      <br />
      <sub>Inspect local token flow and runtime events instead of treating cost as a black box.</sub>
    </td>
  </tr>
</table>

## Quickstart

Elephant Agent has two supported product shapes.

### 1. macOS desktop app (recommended)

Use this path for the full local desktop workspace: Chat / Wake, Paths, Personal
Model, Herd, skills, messaging, calendar, usage, and settings in one native app.

1. Download the latest macOS build from [GitHub Releases](https://github.com/agentic-in/elephant-agent/releases/latest).
2. Open `Elephant Agent.app`.
3. Create your first elephant, choose a provider, and set curiosity effort.
4. Return through Chat / Wake when you want Mother to continue the same path.

### 2. CLI + Dashboard (Linux / Cloud)

Use this path for Linux, cloud machines, SSH workflows, and terminal-first
operators. The CLI is the daily terminal surface; the Dashboard is the visual
inspection surface for Personal Model, evidence, jobs, skills, and runtime
state.

<table>
  <tr>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/cli-wake.jpg" alt="Elephant Agent CLI wake session" />
      <br />
      <strong>CLI</strong>
    </td>
    <td width="50%">
      <img src="apps/site/static/assets/screenshots/dashboard-personal-model.jpg" alt="Elephant Agent Dashboard Personal Model map" />
      <br />
      <strong>Dashboard</strong>
    </td>
  </tr>
</table>

Install:

```bash
curl -fsSL https://elephant.agentic-in.ai/install.sh | bash
```

First run:

```bash
elephant init        # choose identity, provider, and curiosity effort
elephant status      # check provider and local runtime readiness
elephant wake        # enter the chat TUI
elephant dashboard   # open Personal Model, questions, evidence, and runtime state
```

For remote or cloud use, `elephant dashboard --no-open` prints the local URL so
you can attach through your preferred tunnel or browser setup.

## Read More

README and the homepage stay product-first. The deeper system story lives here:

- [Read the docs →](https://elephant.agentic-in.ai/docs/)
- [Read the paper →](https://elephant.agentic-in.ai/paper/)
- [Read the blog →](https://elephant.agentic-in.ai/blog/personal-ai-you-create/)

## Contributors

<p align="center">
  <img src="docs/paper/assets/agentic-intelligence-lab-lockup.png" alt="Agentic Intelligence Lab" width="320" />
</p>

<p align="center">
  <bold>
    Agentic Intelligence Lab
  </bold>
</p>
