@aman_asmuei/aman-agent 0.5.1 → 0.6.1

package/README.md

@@ -18,7 +18,7 @@
    
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT License" /></a>
   &nbsp;
-  <img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 20+" />
   &nbsp;
   <a href="https://github.com/amanasmuei/aman"><img src="https://img.shields.io/badge/part_of-aman_ecosystem-ff6b35?style=for-the-badge" alt="aman ecosystem" /></a>
 </p>
@@ -28,6 +28,10 @@
   extracts knowledge silently, and adapts to your time of day — all running locally.
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/amanasmuei/aman-agent/main/docs/demo/demo.gif" alt="aman-agent demo" width="720" />
+</p>
+
 <p align="center">
   <a href="#-quick-start">Quick Start</a> &bull;
   <a href="#-intelligent-companion-features">Features</a> &bull;
@@ -39,6 +43,26 @@
 
 ---
 
+## What's New in v0.6.0
+
+> **Zero to Wow** — the first 60 seconds are now magical.
+
+| Feature | Before | After |
+|:---|:---|:---|
+| **Onboarding** | 3-4 prompts for API key/model | Auto-detects from env vars |
+| **Ecosystem setup** | Manual, separate CLI | `aman-agent init` wizard with persona presets |
+| **First session** | Empty prompt | Agent introduces itself, asks your name |
+| **Returning session** | Raw context dump | "Welcome back. Last time we talked about..." |
+| **Memory storage** | "Remember X? (y/N)" interruptions | Silent auto-store, undo with `/memory clear` |
+| **Output** | Raw text | Markdown rendering with response framing |
+| **Errors** | "401 Unauthorized" | "API key invalid. Run /reconfig to fix." |
+| **Feature discovery** | Read the README | Progressive hints at the right moment |
+| **New commands** | — | `/memory timeline`, upgraded `/doctor` |
+
+<a href="https://github.com/amanasmuei/aman-agent/releases/tag/v0.6.0">Full release notes</a>
+
+---
+
 ## The Problem
 
 AI coding assistants forget everything between sessions. You re-explain your stack, preferences, and boundaries every time. There's no single place where your AI loads its full context and just *works*.
@@ -69,9 +93,28 @@ npx @aman_asmuei/aman-agent
 npm install -g @aman_asmuei/aman-agent
 ```
 
-### 2. Configure
+**Zero config if you already have an API key in your environment:**
+
+```bash
+# aman-agent auto-detects these (in priority order):
+export ANTHROPIC_API_KEY="sk-ant-..."   # → uses Claude Sonnet 4.6
+export OPENAI_API_KEY="sk-..."          # → uses GPT-4o
+# Or if Ollama is running locally      # → uses llama3.2
+```
+
+No env var? First run prompts for your LLM provider, API key, and model.
 
-First run prompts for your LLM provider, API key, and model. Config saved to `~/.aman-agent/config.json`.
+### 2. (Optional) Set up your companion
+
+```bash
+# Guided wizard — pick a persona preset
+aman-agent init
+
+# Choose from: Coding Partner, Creative Collaborator,
+# Personal Assistant, Learning Buddy, or Minimal
+```
+
+Or just skip this — aman-agent auto-creates a default profile on first run.
 
 ### 3. Talk
 
@@ -87,35 +130,83 @@ aman-agent --budget 12000
 
 ## Intelligent Companion Features
 
-### Per-Message Memory Recall
+### Per-Message Memory Recall with Progressive Disclosure
 
-Every message you send triggers a semantic search against your memory database. Relevant memories are injected into the AI's context for *that turn only* — so the AI always has the right context without bloating the conversation.
+Every message you send triggers a semantic search against your memory database. Results use **progressive disclosure** — a compact index (~50-100 tokens) is injected instead of full content (~500-1000 tokens), giving **~10x token savings**. The agent shows the cost:
 
 ```
 You > Let's set up the auth service
 
+  [memories: ~47 tokens]
+
   Agent recalls:
-  - [decision] Auth service uses JWT tokens (confidence: 0.92)
-  - [preference] User prefers PostgreSQL (confidence: 0.88)
-  - [fact] Auth middleware rewrite driven by compliance (confidence: 0.75)
+  a1b2c3d4 [decision] Auth service uses JWT tokens... (92%)
+  e5f6g7h8 [preference] User prefers PostgreSQL... (88%)
+  i9j0k1l2 [fact] Auth middleware rewrite driven by compliance... (75%)
 
 Aman > Based on our previous decisions, I'll set up JWT-based auth
        with PostgreSQL, keeping the compliance requirements in mind...
 ```
 
-### Hybrid Memory Extraction
+### Silent Memory Extraction
 
-After every response, the agent analyzes the conversation and extracts memories worth keeping. Preferences, facts, patterns, and topology are stored silently. Decisions and corrections require your confirmation.
+After every response, the agent analyzes the conversation and extracts memories worth keeping — preferences, facts, patterns, decisions, corrections, and topology are all stored automatically. No confirmation prompts interrupting your flow.
 
 ```
 You > I think we should go with microservices for the payment system
 
 Aman > That makes sense given the compliance isolation requirements...
 
-  Remember: "Payment system will use microservices architecture"? (y/N) y
   [1 memory stored]
 ```
 
+Don't want something remembered? Use `/memory search` to find it and `/memory clear` to remove it.
+
+### Rich Terminal Output
+
+Responses are rendered with full markdown formatting — **bold**, *italic*, `code`, code blocks, tables, lists, and headings all display beautifully in your terminal. Responses are framed with visual dividers:
+
+```
+ Aman ──────────────────────────────────────────────
+
+  Here's how to set up Docker for this project...
+
+ ──────────────────────────────── memories: ~45 tokens
+```
+
+### First-Run & Returning Greeting
+
+**First session:** Your companion introduces itself and asks your name — the relationship starts naturally.
+
+**Returning sessions:** A warm one-liner greets you with context from your last conversation:
+
+```
+  Welcome back. Last time we talked about your Duit Raya tracker.
+  Reminder: Submit PR for auth refactor (due today)
+```
+
+### Progressive Feature Discovery
+
+aman-agent surfaces tips about features you haven't tried yet, at the right moment:
+
+```
+  Tip: Teach me multi-step processes with /workflows add
+```
+
+One hint per session, never repeated. Disable with `hooks.featureHints: false`.
+
+### Human-Readable Errors
+
+No more cryptic API errors. Every known error maps to an actionable message:
+
+```
+  API key invalid. Run /reconfig to fix.
+  Rate limited. I'll retry automatically.
+  Network error. Check your internet connection.
+```
+
+Failed messages are preserved — just press Enter to retry naturally.
+
 ### LLM-Powered Context Summarization
 
 When the conversation gets long, the agent uses your LLM to generate real summaries — preserving decisions, preferences, and action items. No more losing critical context to 150-character truncation.
@@ -128,6 +219,18 @@ When the AI needs multiple tools, they run in parallel via `Promise.all` instead
 
 LLM calls and MCP tool calls automatically retry on transient errors (rate limits, timeouts) with exponential backoff and jitter. Auth errors fail immediately.
 
+### Passive Tool Observation Capture
+
+Every tool the AI executes is automatically logged to amem's conversation log — tool name, input, and result. This happens passively (fire-and-forget) without slowing down the agent. Your AI builds a complete history of what it *did*, not just what it *said*.
+
+### Token Cost Visibility
+
+Every memory recall shows how many tokens it costs, so you always know the overhead:
+
+```
+  [memories: ~47 tokens]
+```
+
 ### Time-Aware Greetings
 
 The agent knows the time of day and day of week. It adapts its tone naturally — you'll notice the difference between a morning and a late-night session.
@@ -199,7 +302,7 @@ Every operation that can fail logs to `~/.aman-agent/debug.log` with structured
 │   │ 4. Execute tools in parallel (with guardrails) │     │
 │   │ 5. Extract memories from response              │     │
 │   │    - Auto-store: preferences, facts, patterns  │     │
-│   │    - Confirm: decisions, corrections           │     │
+│   │    - All types auto-stored silently             │     │
 │   └────────────────────────────────────────────────┘     │
 │                                                          │
 │   Context Management                                     │
@@ -239,7 +342,7 @@ Every operation that can fail logs to `~/.aman-agent/debug.log` with structured
 | `/tools` | View tools `[add\|remove ...]` |
 | `/skills` | View skills `[install\|uninstall ...]` |
 | `/eval` | View evaluation `[milestone ...]` |
-| `/memory` | View memories `[search\|clear ...]` |
+| `/memory` | View memories `[search\|clear\|timeline]` |
 | `/decisions` | View decision log `[<project>]` |
 | `/export` | Export conversation to markdown |
 | `/debug` | Show debug log (last 20 entries) |
@@ -287,7 +390,7 @@ Default budget: 8,000 tokens. Override with `--budget`.
 
 | Provider | Models | Tool Use | Streaming |
 |:---|:---|:---|:---|
-| **Anthropic** | Claude Sonnet 4.5, Opus 4.6, Haiku 4.5 | Full | Full (with tools) |
+| **Anthropic** | Claude Sonnet 4.6, Opus 4.6, Haiku 4.5 | Full | Full (with tools) |
 | **OpenAI** | GPT-4o, GPT-4o Mini, o3 | Full | Full (with tools) |
 | **Ollama** | Llama, Mistral, Gemma, any local model | Text only | Full |
 
@@ -301,7 +404,7 @@ Config is stored in `~/.aman-agent/config.json`:
 {
   "provider": "anthropic",
   "apiKey": "sk-ant-...",
-  "model": "claude-sonnet-4-5-20250514",
+  "model": "claude-sonnet-4-6",
   "hooks": {
     "memoryRecall": true,
     "sessionResume": true,
@@ -309,7 +412,8 @@ Config is stored in `~/.aman-agent/config.json`:
     "workflowSuggest": true,
     "evalPrompt": true,
     "autoSessionSave": true,
-    "extractMemories": true
+    "extractMemories": true,
+    "featureHints": true
   }
 }
 ```
@@ -332,6 +436,7 @@ All hooks are on by default. Disable any in `config.json`:
 | `evalPrompt` | Session rating on exit |
 | `autoSessionSave` | Save conversation to amem on exit |
 | `extractMemories` | Auto-extract memories from conversation |
+| `featureHints` | Show progressive feature discovery tips |
 
 > Treat the config file like a credential — it contains your API key.
 
@@ -380,7 +485,7 @@ aman
 | Identity system | 7 portable layers | None | None |
 | Memory | amem (SQLite + embeddings + graph) | Postgres + embeddings | None |
 | Per-message recall | Progressive disclosure (~10x token savings) | Yes | No |
-| Learns from conversation | Auto-extract (hybrid confirm) | Requires configuration | No |
+| Learns from conversation | Auto-extract (silent) | Requires configuration | No |
 | Guardrail enforcement | Runtime tool blocking | None | None |
 | Reminders | Persistent, deadline-aware | None | None |
 | Context compression | LLM-powered summarization | Archival system | Truncation |
@@ -415,7 +520,7 @@ aman
 git clone https://github.com/amanasmuei/aman-agent.git
 cd aman-agent && npm install
 npm run build   # zero errors
-npm test        # 84 tests pass
+npm test        # 111 tests pass
 ```
 
 PRs welcome. See [Issues](https://github.com/amanasmuei/aman-agent/issues).