@heyamiko/amiko-cli 0.4.1 → 0.4.8

package/PLAN.md

@@ -0,0 +1,113 @@
+# Amiko CLI Agent Plan
+
+## Goals
+- Build a TypeScript CLI agent for Amiko.
+- Use `@mariozechner/pi-coding-agent` as the agent backend.
+- Use QMD (`qmd`) for memory search/retrieval.
+- Use Ink for the TUI.
+- Maintain a workspace folder with persistent memory files and per-session logs.
+
+## Non-Goals (for this phase)
+- Implement additional chat channels (WhatsApp/Telegram/etc.).
+- Build a separate daemon or multi-client gateway unless required later.
+- Ship packaged binaries or installers.
+
+## Reference Architecture (Moltbot-inspired)
+Moltbot’s architecture separates a long-lived Gateway (control plane) from clients that connect over a single transport (WebSocket), and keeps the Gateway as the only process that owns external integrations. We’ll mirror this separation in a CLI-friendly way:
+
+1) **Client/UI** (Ink TUI)  
+2) **Agent Runtime** (pi-coding-agent adapter)  
+3) **Workspace + Memory** (local files + QMD search)
+
+For this initial CLI-only scope, all three can run in a single process. The boundary will be maintained in code so we can later split into a Gateway daemon + multiple clients if needed.
+
+## Workspace Layout (local-first memory)
+Workspace root: user-configurable (default: `~/.amiko` or project-provided path)
+
+```
+workspace/
+  IDENTITY.md
+  PERSONALITY.md
+  MEMORY.md
+  sessions/
+    yyyy-mm-dd-<id>.md
+```
+
+Rules:
+- `IDENTITY.md`: stable identity and role.
+- `PERSONALITY.md`: tone, style, and behavior defaults.
+- `MEMORY.md`: long-term memory (summaries, facts, preferences).
+- `sessions/yyyy-mm-dd-id.md`: per-session transcript/memory log.
+
+## Components
+
+### 1) CLI + TUI (Ink)
+- Interactive chat UI with streaming output and status panes.
+- Commands: `/exit`, `/help`, `/memory`, `/session`, `/search`, `/plan` (minimal set).
+- Visual status: model, workspace path, memory hits, active tools.
+
+### 2) Agent Backend Adapter (pi-coding-agent)
+- Wrap pi-coding-agent to expose a stable API for:
+  - send user message
+  - stream assistant output
+  - tool invocation
+  - interrupts/cancel
+- Keep backend configurable (model, provider, temperature, etc.).
+
+### 3) Memory & Retrieval (QMD)
+- Treat QMD as an external CLI tool.
+- Index the workspace and any configured additional folders.
+- Retrieval pipeline:
+  1) On each user query, run `qmd query` (hybrid + rerank) over workspace.
+  2) Pull top N snippets or full docs with `qmd get`.
+  3) Inject memory context into the agent prompt.
+- Provide a `/search <query>` command to show memory hits.
+
+### 4) Session Persistence
+- Append every user/assistant turn to `sessions/yyyy-mm-dd-id.md`.
+- Periodically summarize into `MEMORY.md` (manual for v1, automated later).
+
+## Data Flow (per message)
+1) User enters message in Ink UI.
+2) Memory search with QMD (optional based on size + settings).
+3) Build prompt from:
+   - IDENTITY.md
+   - PERSONALITY.md
+   - MEMORY.md (summary)
+   - Retrieved session/memory snippets
+4) Send to pi-coding-agent.
+5) Stream output to UI.
+6) Persist to session file; optional memory rollup.
+
+## Implementation Milestones
+
+### Milestone 1: Skeleton + Workspace
+- Initialize TS project with Ink.
+- Create workspace loader + validator.
+- Create session file writer.
+
+### Milestone 2: Agent Backend Integration
+- Adapter around pi-coding-agent.
+- Streaming to UI.
+- Basic command handling.
+
+### Milestone 3: QMD Memory Search
+- Integrate QMD CLI calls.
+- Add `/search` command.
+- Inject memory hits into prompts.
+
+### Milestone 4: Polishing
+- Config file handling.
+- Better errors/logging.
+- Memory rollup helpers.
+
+## Risks / Open Questions
+- QMD install/availability assumptions (global `qmd` binary).
+- Whether pi-coding-agent provides a clean streaming API for Ink.
+- Prompt size and memory insertion strategy.
+
+## Success Criteria
+- CLI runs with Ink UI.
+- Sends prompts through pi-coding-agent.
+- Uses QMD to retrieve memory snippets.
+- Writes long-term and per-session memory files.