@aman_asmuei/aman-agent 0.5.0 → 0.6.0

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;
@@ -69,9 +73,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 +110,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 +199,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 +282,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 +322,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 +370,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 +384,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 +392,8 @@ Config is stored in `~/.aman-agent/config.json`:
     "workflowSuggest": true,
     "evalPrompt": true,
     "autoSessionSave": true,
-    "extractMemories": true
+    "extractMemories": true,
+    "featureHints": true
   }
 }
 ```
@@ -332,6 +416,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.
 
@@ -373,17 +458,39 @@ aman
 
 ## What Makes This Different
 
-| Feature | aman-agent | MemoryCore / Others |
-|:---|:---|:---|
-| Memory storage | SQLite + embeddings + knowledge graph | Markdown files |
-| Per-message recall | Semantic search every turn | Static blob at session start |
-| Memory extraction | Auto-extract from conversation (LLM) | AI must manually write to files |
-| Context compression | LLM-powered summarization | Truncation or line limits |
-| Tool execution | Parallel with guardrail checks | Sequential or none |
-| Reminders | Persistent, cross-session, deadline-aware | None |
-| Error handling | Structured JSON debug log | Silent failures |
-| Multi-LLM | Anthropic, OpenAI, Ollama | Usually single provider |
-| Reliability | Retry with exponential backoff | Single attempt |
+### aman-agent vs other companion runtimes
+
+| Feature | aman-agent | Letta / MemGPT | Raw LLM CLI |
+|:---|:---|:---|:---|
+| 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 (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 |
+| Tool observation capture | Passive logging of all tool calls | None | None |
+| Token cost visibility | Shows memory injection cost per turn | None | None |
+| Multi-LLM | Anthropic, OpenAI, Ollama | OpenAI-focused | Single provider |
+| Tool execution | Parallel with guardrails | Sequential | None |
+
+### amem vs other memory layers
+
+| Feature | amem | claude-mem (40K stars) | mem0 |
+|:---|:---|:---|:---|
+| Works with | Any MCP client | Claude Code only | OpenAI-focused |
+| Storage | SQLite + local embeddings | SQLite + Chroma vectors | Cloud vector DB |
+| Progressive disclosure | Compact index + on-demand detail | Yes (10x savings) | No |
+| Memory types | 6 typed (correction > decision > fact) | Untyped observations | Untyped blobs |
+| Knowledge graph | Typed relations between memories | None | None |
+| Reminders | Persistent, deadline-aware | None | None |
+| Scoring | relevance x recency x confidence x importance | Recency-based | Similarity only |
+| Consolidation | Auto merge/prune/promote | None | None |
+| Version history | Immutable snapshots | Immutable observations | None |
+| Token cost visibility | Shown per recall | Shown per injection | None |
+| License | MIT | AGPL-3.0 | Apache-2.0 |
+
+> **claude-mem** excels at capturing what Claude Code *did*. **amem** is a structured memory system that works with *any* MCP client, with typed memories, a knowledge graph, reminders, progressive disclosure, and consolidation.
 
 ---
 
@@ -393,7 +500,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).