agentram 0.1.21 → 0.1.30

package/README.md

@@ -1,4 +1,4 @@
-# AgentRAM
+# AgentRAM
 
 Async, model-agnostic Working RAM for coding agents such as Codex, Claude Code, Cursor, and custom MCP clients.
 
@@ -358,20 +358,20 @@ Minimum usage pattern:
 
 AgentRAM can bind multiple coding model endpoints and let Claude Code or MCP clients orchestrate them in parallel. This keeps the `free-code` style command registry, but adds project RAM, Goal Stack, and multi-agent model routing.
 
-Bind models:
-
-```bash
-agentram bind-model claude-subagent agentram-reviewer --role reviewer
-agentram bind-model claude claude-3-5-sonnet-latest --role reviewer --api-key-env ANTHROPIC_API_KEY
-agentram bind-model openai-compatible qwen2.5-coder --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
-```
-
-Claude Code subagent endpoint uses your local Claude CLI entrypoint. `model` is the subagent name from `.claude/agents`, for example `agentram-reviewer` or `agentram-planner`. Default command is `claude -p`. Override command when needed:
-
-```bash
-set AGENTRAM_CLAUDE_COMMAND=claude
-agentram bind-model claude-subagent agentram-reviewer --role reviewer
-```
+Bind models:
+
+```bash
+agentram bind-model claude-subagent agentram-reviewer --role reviewer
+agentram bind-model claude claude-3-5-sonnet-latest --role reviewer --api-key-env ANTHROPIC_API_KEY
+agentram bind-model openai-compatible qwen2.5-coder --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
+```
+
+Claude Code subagent endpoint uses your local Claude CLI entrypoint. `model` is the subagent name from `.claude/agents`, for example `agentram-reviewer` or `agentram-planner`. Default command is `claude -p`. Override command when needed:
+
+```bash
+set AGENTRAM_CLAUDE_COMMAND=claude
+agentram bind-model claude-subagent agentram-reviewer --role reviewer
+```
 
 Build a dry-run orchestration plan:
 
@@ -396,12 +396,12 @@ agentram_run_coding_orchestration
 
 TUI slash commands. Plain text only records/retrieves RAM; use `/ask` to call bound models:
 
-```text
-/bind-model claude-subagent agentram-reviewer role=reviewer
-/bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY
-/models
-/orchestrate review CLI orchestration
-/ask xin chào
+```text
+/bind-model claude-subagent agentram-reviewer role=reviewer
+/bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY
+/models
+/orchestrate review CLI orchestration
+/ask xin chào
 ```
 
 Storage:
@@ -876,7 +876,7 @@ Inside TUI:
 
 ```text
 /bind-model openai-compatible Agentic --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
-/ask xin chào
+/ask xin chào
 ```
 
 Do not paste raw API keys into `/bind-model`. `api_key_env` means environment variable name, e.g. `OPENAI_API_KEY`.
@@ -908,133 +908,146 @@ If `/ask` shows connection refused, the configured OpenAI-compatible server is n
 
 ```text
 /bind-model openai-compatible Agentic --role coder --base-url http://localhost:8000/v1 --api-key-env OPENAI_API_KEY
-/ask xin chào
+/ask xin chào
 ```
 
 Start your local server first, or change `--base-url` to the provider URL.
-
-## Prompt Router Model
-
-AgentRAM can use a separate small router model before normal prompts. The router classifies each prompt, then sends it to the right path.
-
-```text
-coding   -> bound coding endpoints / Claude subagents
-planning -> Goal Stack and drift check
-memory   -> AgentRAM note ingest
-chat     -> RAM retrieve only
-```
-
-Bind a router model:
-
-```text
-/bind-router openai-compatible qwen2.5:1.5b base_url=http://localhost:8000/v1 api_key_env=OPENAI_API_KEY
-/route on
-```
-
-Then prompt without slash:
-
-```text
-fix adapter.py
-c?p nh?t goal stack
-ghi nh? d�ng Claude subagent
-```
-
-Disable auto routing:
-
-```text
-/route off
-```
-
-## Supervisor + Small Agent Workflow
-
-AgentRAM can run as a two-flow coding agent system, not only as a flat multi-model router.
-
-```text
-agentram
-  |
-  v
-Parse User Request
-  |
-  v
-Supervisor Memory
-  |
-  v
-Task Classifier / Supervisor Plan
-  |----------------------|
-  v                      v
-Main Agent               Small Agent
-(GPT-5.5 Codex)          (Qwen Codex)
-planning/coding/fix      notes/RAM/coding facts
-  |                      |
-  |----------|-----------|
-             v
-Merge + Update Memory
-             |
-             v
-Return Result
-```
-
-Bind workflow agents:
-
-```text
-/bind-agent supervisor claude-subagent agentram-planner
-/bind-agent main openai-compatible gpt-5.5-codex base_url=https://api.example.com/v1 api_key_env=MAIN_AGENT_KEY
-/bind-agent small openai-compatible qwen-codex base_url=http://localhost:8001/v1 api_key_env=SMALL_AGENT_KEY
-/workflow
-```
-
-Then use normal prompts without slash:
-
-```text
-refactor orchestration workflow
-fix bug in adapter.py
-plan next milestone
-```
-
-Runtime behavior:
-
-```text
-Supervisor creates plan -> Main agent executes -> Small agent records RAM notes -> AgentRAM merges result
-```
-
+
+## Prompt Router Model
+
+AgentRAM can use a separate small router model before normal prompts. The router classifies each prompt, then sends it to the right path.
+
+```text
+coding   -> bound coding endpoints / Claude subagents
+planning -> Goal Stack and drift check
+memory   -> AgentRAM note ingest
+chat     -> RAM retrieve only
+```
+
+Bind a router model:
+
+```text
+/bind-router openai-compatible qwen2.5:1.5b base_url=http://localhost:8000/v1 api_key_env=OPENAI_API_KEY
+/route on
+```
+
+Then prompt without slash:
+
+```text
+fix adapter.py
+cap nhat goal stack
+ghi nho dung Claude subagent
+```
+
+Disable auto routing:
+
+```text
+/route off
+```
+
+## Supervisor + Small Agent Workflow
+
+AgentRAM can run as a two-flow coding agent system, not only as a flat multi-model router.
+
+```text
+agentram
+  |
+  v
+Parse User Request
+  |
+  v
+Supervisor Memory
+  |
+  v
+Task Classifier / Supervisor Plan
+  |----------------------|
+  v                      v
+Main Agent
+(Codex CLI / Claude Code / OpenAI-compatible)
+planning/coding/fix, may edit files when bound to CLI provider
+  |
+  v
+Small Agent
+(Qwen/OpenAI-compatible/Anthropic)
+notes/RAM/coding facts only
+  |
+  v
+Merge + Update Memory
+  |
+  v
+Return Result
+```
+
+Bind workflow agents:
+
+```text
+/bind-agent supervisor openai-compatible supervisor-model base_url=https://api.example.com/v1 api_key_env=SUPERVISOR_AGENT_KEY
+/bind-agent main codex-cli current base_url="codex exec"
+/bind-agent small openai-compatible qwen-codex base_url=http://localhost:8001/v1 api_key_env=SMALL_AGENT_KEY
+/workflow
+```
+
+Then use normal prompts without slash:
+
+```text
+refactor orchestration workflow
+fix bug in adapter.py
+plan next milestone
+```
+
+Runtime behavior:
+
+```text
+Supervisor creates plan -> Main CLI coding agent edits/returns result -> Small agent reads plan + main result and records RAM notes -> AgentRAM merges result
+```
+
 Small agent should not own big direction. It records plans, decisions, files, risks, next tasks, and coding facts into RAM.
-
-## Textual TUI
-
-Install rich terminal UI with native scrollable chat pane:
-
-```bash
-pip install agentram[tui]
-agentram tui
-```
-
+
+CLI coding providers for file edits:
+
+```text
+/bind-agent main codex-cli current base_url="codex exec"
+/bind-agent main claude-code claude base_url="claude"
+```
+
+Use `codex-cli` or `claude-code` only for the main agent when you want a coding agent subprocess that can inspect and edit files. Keep the small agent on an LLM-only provider so it records notes but does not edit code.
+
+## Textual TUI
+
+Install rich terminal UI with native scrollable chat pane:
+
+```bash
+pip install agentram[tui]
+agentram tui
+```
+
 When `textual` is installed, AgentRAM uses a real full-screen TUI with mouse wheel scrolling inside the chat frame. If `textual` is missing, it falls back to the basic print-based terminal UI.
-
-## npm Python Dependencies
-
-When installed through npm, AgentRAM runs a `postinstall` step that tries to install Python TUI dependencies for the Python interpreter used by `agentram`:
-
-```text
-textual>=0.80
-prompt_toolkit>=3.0
-```
-
-Set target Python before install when needed:
-
-```powershell
-$env:PYTHON="C:\Users\admin\anaconda3\python.exe"
-npm install -g agentram@latest
-```
-
-Skip automatic Python dependency install:
-
-```powershell
-$env:AGENTRAM_SKIP_PY_DEPS="1"
-npm install -g agentram@latest
-```
-
-If auto install fails, install manually:
-
-```powershell
-python -m pip install textual prompt_toolkit
+
+## npm Python Dependencies
+
+When installed through npm, AgentRAM runs a `postinstall` step that tries to install Python TUI dependencies for the Python interpreter used by `agentram`:
+
+```text
+textual>=0.80
+prompt_toolkit>=3.0
+```
+
+Set target Python before install when needed:
+
+```powershell
+$env:PYTHON="C:\Users\admin\anaconda3\python.exe"
+npm install -g agentram@latest
+```
+
+Skip automatic Python dependency install:
+
+```powershell
+$env:AGENTRAM_SKIP_PY_DEPS="1"
+npm install -g agentram@latest
+```
+
+If auto install fails, install manually:
+
+```powershell
+python -m pip install textual prompt_toolkit
 ```