Metadata-Version: 2.4
Name: elephant-agent
Version: 1.0.0.dev20260526090301
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>Agency-first personal AI.</strong><br />
    A correctable Personal Model for Identity, World, Pulse, and Journey.
  </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>


## Why Another Agent?

Agent products are exploding. Coding agents, workflow agents, local personal
agents, skill systems, and messaging agents all point in the same direction:
AI can now do more of the work.

That is useful, but it is not enough.

When execution gets cheaper, the bottleneck moves. The hard question becomes:
what happens to the person behind the agents? If AI performs more of the work,
how does the user keep judgment, continuity, self-understanding, and growth
instead of becoming a prompt sender and result approver?

Elephant Agent is built around that next question. Its position is **L4
personal AI**: not only helping the agent do more, but helping the person keep
growing as agents do more.

## Personal Agent Levels

| Level | Core question | Common product shape | Public examples | Elephant Agent's stance |
|---|---|---|---|---|
| **L1 — Do work** | Can AI execute tasks for me? | Coding agents, workflow agents, tool use, browser/file/shell automation. | Claude Code, Cursor, Devin, Codex-style agents. | Useful, but not the center. Elephant can use tools, but execution alone does not preserve the person. |
| **L2 — Carry context** | Can the agent remember enough to stop starting over? | Persistent memory, cross-session recall, heartbeats, local personal assistants, messaging gateways. | [OpenClaw](https://openclaw.ai/) publicly emphasizes local agents, chat apps, persistent memory, full system access, skills, plugins, and integrations. | Necessary foundation. Elephant keeps continuity, but memory is support, not the product. |
| **L3 — Improve procedures** | Can the agent evolve its own rules, skills, and workflows? | Self-improving skills, procedural memory, autonomous skill creation, user modeling, recurring automation. | [Hermes Agent](https://hermes-ai.net/) publicly positions itself around a self-improving learning loop, skill creation, skill refinement, recall, and user modeling. | Important downstream capability. Elephant keeps skills visible and governed, but skills orbit the Personal Model. |
| **L4 — Grow the person** | Can personal AI return judgment, evidence, questions, and reflection to the user? | Correctable Personal Model, evidence-backed claims, user-paced curiosity, reflection, review, and human agency boundaries. | This is Elephant Agent's product position. | Elephant is designed for L4: agents may do more, but the person should not think less. |

OpenClaw shows how far a local personal automation agent can go. Hermes shows
how far self-improving skill loops can go. Elephant asks the next question:
when agents do and learn more, how does the person stay in the loop and keep
getting stronger?

## What Elephant Agent Is

Elephant Agent is not a memory app, a skill marketplace, or another wrapper
around tool calls.

It is a **Personal-Model-first understanding system**. It grows a correctable,
evidence-backed model of what should shape future help:

- **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.

The goal is not to remember everything. The goal is to understand what matters,
show why it matters, and let you change it.

## Why an Elephant?

<p align="center">
  <img src="apps/site/static/assets/brand/elephant-logo.png" alt="Elephant Agent logo" width="250" />
</p>


The old saying is close to true, but the beautiful part is not storage.
Elephants remember **with meaning**.

They recognize companions by sight and smell, remember danger cues, and return
to important places long after the last visit. Older matriarchs can guide a herd
through hard seasons because memory has become **practical judgment**: who is
safe, where water may be found, and which warning signs deserve attention.

That is the inspiration for Elephant Agent: memory that becomes **care**,
**context**, and **better judgment**.

For personal AI, that distinction matters. Memory is not valuable because it is
large. Memory is valuable when it becomes practical judgment while still
remaining correctable by the person it is meant to help.

## From Memory to Agency

Most AI still asks you to **begin again**. You explain the same project, the same
people, the same constraints, the same decisions, and the same hard-won lessons.
Longer context windows help for a while, but they do not solve the deeper
problem: a personal AI should know **which experiences are worth turning into
future judgment**.

Elephant Agent is built around that idea. It does not try to preserve every
transcript. It grows a **correctable understanding** of the **paths**, **people**,
**risks**, **rhythms**, and **decisions** that should shape future help.

- It **remembers less**, but **understands deeper**.
- It **picks up the right thread** instead of replaying the whole past.
- It **asks gently** when one missing answer would change how it helps.
- It **shows evidence**, accepts correction, and lets silence stand.
- It helps you **do more without thinking less** by returning experience,
  tradeoffs, and questions to you.

This is the agency-first part: Elephant Agent does not evolve by collecting more
transcripts or blindly adding skills. It evolves around you as curiosity and
background reflect jobs turn lived evidence into a clearer, correctable
Personal Model.

One `elephant` is a durable companion for a line of work or life context. Many
elephants form a `herd`.

## How the Personal Model Works

Elephant Agent is not trying to collect a complete profile. It learns what has durable
value for future help:

<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>

| Lens | What it carries forward |
|---|---|
| **Identity** | Stable self-description, values, decision style, boundaries, and durable preferences. |
| **World** | Projects, people, tools, places, vocabulary, and relationships that shape your context. |
| **Pulse** | Current focus, active pressure, recent constraints, mood patterns, and temporary priorities. |
| **Journey** | Past experiences, lessons, failures, recovery patterns, and long-running growth. |

That learning comes from governed loops:

- **Grounded learning** from explicit remembers, corrections, and dashboard edits.
- **Curiosity-driven learning** from one useful question when a gap would change future help.
- **Reflect-driven background learning** from agents that read Episode steps after close, idle, diary, or manual triggers.
- **Skill fit learning** from visible capability use while keeping durable understanding inspectable.

## Correctable, Not Hidden

Elephant Agent should not shape you through an invisible profile. Durable
understanding is made of claims with status, confidence, and source episode
provenance.

| Move | Meaning |
|---|---|
| **Remember** | Add a useful claim that can shape future help. |
| **Correct** | Replace a wrong or stale claim. |
| **Forget** | Retire a claim so it no longer shapes replies. |
| **Dispute** | Keep uncertainty visible until the user clarifies. |
| **Why?** | Trace a claim back to the Episode and Step evidence behind it. |

The retrieval rule is strict: conversation search and embeddings can provide
support, but they do not become truth by themselves. If Elephant Agent cannot
find reliable Personal Model support, `no_match` is a feature, not a failure.

## Curiosity, At Your Pace

At `elephant init`, you choose how curious your Elephant Agent should be:

| Curiosity effort | What it feels like |
|---|---|
| **Quiet** | Elephant Agent mostly waits and asks rarely. |
| **Balanced** | Elephant Agent asks at natural pauses when the answer would help. |
| **Active** | Elephant Agent is more willing to check in and learn, while staying optional. |

Every question belongs to a Personal Model lens and exists for a reason: a gap,
a conflict, a stale pulse, or an adaptation that would improve future help.
Questions are visible and dismissible. Silence always wins.

Curiosity is proactive about understanding, not pushy about action.

## You Stay In Control

Open the dashboard to see and shape what Elephant Agent understands:

- **You** — active Identity, World, Pulse, and Journey claims.
- **Why** — evidence behind a claim, shown when you inspect it.
- **Questions** — open, asked, answered, and dismissed curiosity prompts.
- **Evidence** — the trail behind understanding, not hidden prompt truth.

You can correct or forget claims, answer or dismiss questions, and keep Elephant Agent’s
understanding aligned with who you are now.

This is the product boundary: agents may execute, remember, and reflect, but
your identity, values, relationships, and growth remain yours to inspect and
correct.

## Quickstart

Install Elephant Agent, create your first named elephant, then come back through `wake` whenever
you want to continue.

### Install

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

### First run

```bash
elephant init        # choose identity, provider, and curiosity effort
elephant herd new    # create another named elephant when you need one
elephant wake        # enter the chat TUI
elephant dashboard   # open You, Questions, and Evidence
```

## How It Deepens

| Day 1 | Week 1 | Month 1 | Month 3 |
|---|---|---|---|
| It knows your first anchors | It knows the project and people in view | It asks better questions and explains why | It helps turn repeated experience into correctable judgment |

## Paper and blog

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

- [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>
