@aman_asmuei/aman-agent 0.42.0 → 0.43.0

package/README.md

@@ -343,6 +343,8 @@ npx @aman_asmuei/aman-agent
 
 ---
 
+> **New to the ecosystem?** See [docs/ecosystem.md](docs/ecosystem.md) for "which package do I install, and when" + the full package relationship diagram.
+
 ## Architecture at a Glance
 
 aman-agent is the **runtime** at the center of the aman ecosystem — 78 TypeScript modules that stitch together memory, identity, orchestration, and any LLM into one coherent system.
@@ -443,6 +445,50 @@ flowchart TB
 
 ---
 
+## Install tiers — pick what you need
+
+The aman ecosystem is ~10 packages. You don't need them all. Pick a tier:
+
+### Minimal (2 packages, 2 minutes)
+
+Just `aman-agent` + persistent memory. Standalone CLI, works with any LLM provider. Best for "does this feel useful?" evaluation.
+
+```bash
+npm install -g @aman_asmuei/aman-agent @aman_asmuei/amem-core
+# or, once you have Node 18+:
+curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-agent/main/bin/aman-setup.sh | bash
+```
+
+What you get: `aman-agent` CLI, per-message memory recall, memory extraction, `/memory` commands.
+
+### Productive (5 packages, 10 minutes)
+
+Minimal + identity + guardrails + Claude Code integration. Adds your AI's personality, rules the LLM must respect, and first-class Claude Code plugin support.
+
+```bash
+npm install -g @aman_asmuei/aman-agent @aman_asmuei/amem-core \
+  @aman_asmuei/acore-core @aman_asmuei/arules-core @aman_asmuei/aman-mcp
+# + install the Claude Code plugin:
+# see aman-claude-code repo README
+```
+
+What you get (on top of Minimal): named companion ("Aman" by default), rule enforcement via `/rules`, auto-loaded ecosystem context at session start, MCP tools for memory/identity/rules from inside Claude Code.
+
+### Complete (all packages, 30 minutes)
+
+Everything: orchestration, multi-agent delegation, showcase personalities, tool installer, skill manager, VS Code Copilot integration.
+
+```bash
+# After Productive, add:
+npm install -g @aman_asmuei/aman-copilot @aman_asmuei/akit @aman_asmuei/askill @aman_asmuei/aman-showcase
+```
+
+What you get (on top of Productive): `/orchestrate` DAG task decomposition, `/delegate` + `/team` multi-agent workflows, `/showcase` 13 personality templates, `/akit` CLI tool manager, `/askill` skill library. VS Code Copilot users also get `aman-copilot` for inline Copilot Chat memory.
+
+**Not sure which tier?** Start with Minimal. You can layer Productive or Complete on top whenever you want — nothing gets overwritten, just extended.
+
+---
+
 ## Quick Start
 
 ### Claude Code plugin (recommended)
@@ -701,6 +747,27 @@ You > Let's add a new endpoint
 /decisions               View your decision log
 ```
 
+### Memory mirror (markdown)
+
+Your memory DB is great for the agent, but sometimes you want memories as **plain Markdown files** you can `grep`, edit in any editor, commit to git, or sync with Dropbox/iCloud across devices. The mirror gives you exactly that — a human-readable copy of every memory that round-trips cleanly back into the DB.
+
+```
+/memory export --to <dir>     One-shot snapshot of all memories as .md files
+/memory mirror status         Show live mirror path, file count, last sync
+/memory mirror rebuild        Re-materialise the mirror from the DB
+/memory sync --from <dir>     Reconstitute the DB from a directory of .md files
+```
+
+**When you want this:**
+
+- **Human-readable backup** — `grep -r "postgres" ~/.aman-agent/memories/` to see every memory that mentions Postgres.
+- **Edit outside the agent** — fix a typo or retire a stale decision in your favourite editor, then run `/memory sync --from ...` (or just restart — startup auto-syncs).
+- **Version-control your memory** — `git init ~/.aman-agent/memories/` and you get a full history of every memory the agent has ever learned.
+- **Multi-device sync** — point the mirror dir at a synced folder (Dropbox, iCloud, Syncthing) and your memories follow you.
+- **No lock-in** — YAML-frontmatter Markdown is readable without aman-agent ever being installed again.
+
+Opt-out: `config.mirror.enabled = false` disables all mirror I/O. Disable auto-sync on startup only with `config.mirror.autoSyncOnStartup = false`.
+
 </details>
 
 <details>

package/bin/aman-setup.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# aman-setup: non-interactive Minimal install.
+# Installs aman-agent + amem-core globally via npm. Requires Node 18+.
+#
+# Advanced tiers (Productive, Complete) require more choices — see
+# the README for the relevant package lists.
+
+set -euo pipefail
+
+echo "=== aman Minimal install ==="
+echo "Installs: aman-agent + amem-core"
+echo ""
+
+if ! command -v node >/dev/null 2>&1; then
+    echo "ERROR: node not found. Install Node 18+ first: https://nodejs.org" >&2
+    exit 1
+fi
+
+NODE_VERSION_MAJOR=$(node -p "process.versions.node.split('.')[0]")
+if [ "$NODE_VERSION_MAJOR" -lt 18 ]; then
+    echo "ERROR: Node 18+ required (you have $(node --version))" >&2
+    exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+    echo "ERROR: npm not found. Reinstall Node from https://nodejs.org" >&2
+    exit 1
+fi
+
+echo "Installing @aman_asmuei/aman-agent + @aman_asmuei/amem-core..."
+npm install -g @aman_asmuei/aman-agent @aman_asmuei/amem-core
+
+echo ""
+echo "=== Done ==="
+echo "Run: aman-agent"
+echo "See the README's 'Install tiers' section for Productive / Complete upgrades."