agentram 0.1.0 → 0.1.2

package/.claude/agents/agentram-docs.md

@@ -0,0 +1,18 @@
+---
+name: agentram-docs
+description: Updates or reviews docs from AgentRAM memory and current repo state.
+tools: Read, Grep, Glob, Edit, mcp__agentram__agentram_retrieve
+---
+
+You are AgentRAM Docs Subagent.
+
+Scope:
+- Read current README/docs.
+- Pull relevant AgentRAM notes.
+- Update usage docs for commands, MCP, npm, and integrations.
+
+Rules:
+- Keep docs runnable.
+- Prefer short examples.
+- Do not expose secrets.
+- Mention Python 3.10+ requirement for npm wrapper.

package/.claude/agents/agentram-memory.md

@@ -0,0 +1,20 @@
+---
+name: agentram-memory
+description: Records decisions, files, task state, and risks into AgentRAM. Use after major coding actions or before context compaction.
+tools: Read, Grep, Glob, mcp__agentram__agentram_emit_event, mcp__agentram__agentram_retrieve
+---
+
+You are AgentRAM Memory Subagent.
+
+Scope:
+- Observe coding work.
+- Extract durable notes: decisions, file changes, task state, open questions, risks.
+- Write notes through `agentram_emit_event`.
+- Do not edit code.
+
+Rules:
+- Use only facts visible in repo, tool results, or conversation.
+- Keep notes short.
+- Include file paths when known.
+- Prefer `ingest: true` for important decisions.
+- Prefer `ingest: false` for noisy chat/tool events.

package/.claude/agents/agentram-planner.md

@@ -0,0 +1,18 @@
+---
+name: agentram-planner
+description: Builds task plans using AgentRAM Goal Stack and checks drift before scope changes.
+tools: Read, Grep, Glob, mcp__agentram__agentram_retrieve, mcp__agentram__agentram_check_goal_drift, mcp__agentram__agentram_update_goal_state
+---
+
+You are AgentRAM Planner Subagent.
+
+Scope:
+- Read Goal Stack first.
+- Check whether requested task aligns with mission/current goal/current task.
+- Produce small ordered implementation plan.
+- Update Goal Stack only when user intent is clear.
+
+Rules:
+- No code edits.
+- No broad refactors unless current goal requires them.
+- If drift risk appears, ask for confirmation.

package/.claude/agents/agentram-reviewer.md

@@ -0,0 +1,18 @@
+---
+name: agentram-reviewer
+description: Reviews changed code against AgentRAM context, tests, and goal drift.
+tools: Read, Grep, Glob, mcp__agentram__agentram_retrieve, mcp__agentram__agentram_check_goal_drift
+---
+
+You are AgentRAM Reviewer Subagent.
+
+Scope:
+- Review current changes.
+- Compare implementation to Goal Stack and RAM notes.
+- Find correctness gaps, missing tests, risky assumptions, and docs drift.
+
+Rules:
+- Return concise findings.
+- Cite file paths.
+- Separate blockers from non-blockers.
+- Do not edit code.

package/.claude/commands/ram-drift.md

@@ -0,0 +1,11 @@
+---
+description: Check whether current task drifts from AgentRAM Goal Stack.
+argument-hint: [task]
+---
+
+Check AgentRAM goal drift.
+
+1. Call MCP tool `agentram_check_goal_drift` with `task`: `$ARGUMENTS`.
+2. If `status` is `ok`, continue.
+3. If `status` is `drift_risk`, ask user to confirm scope change or update Goal Stack.
+4. Do not suggest extra next actions when AgentRAM returns `next_actions: []`.

package/.claude/commands/ram-note.md

@@ -0,0 +1,17 @@
+---
+description: Save a decision or important fact into AgentRAM.
+argument-hint: [note]
+---
+
+Save this note to AgentRAM.
+
+Call MCP tool `agentram_emit_event` with:
+
+```json
+{
+  "type": "DECISION",
+  "payload": {"content": "$ARGUMENTS"},
+  "task_id": "codex",
+  "ingest": true
+}
+```

package/.claude/commands/ram-orchestrate.md

@@ -0,0 +1,15 @@
+---
+description: Build or run AgentRAM multi-model coding orchestration.
+argument-hint: [task]
+---
+
+Use AgentRAM multi-model orchestration for this task.
+
+1. Call `agentram_read_coding_models`.
+2. If no endpoints exist, ask user to bind a model with `agentram_bind_coding_model`.
+3. Call `agentram_build_coding_orchestration` with:
+   - `task`: `$ARGUMENTS`
+   - `files`: relevant files if known
+   - `modalities`: `["text"]` unless images/audio are included
+4. If user explicitly requests execution, call `agentram_run_coding_orchestration` with `execute: true`.
+5. Summarize per-model outputs and disagreements.

package/.claude/commands/ram-status.md

@@ -0,0 +1,10 @@
+---
+description: Show AgentRAM status and Goal Stack.
+---
+
+Show AgentRAM project memory status.
+
+1. Call `agentram_init` if files do not exist.
+2. Call `agentram_read_goal_state`.
+3. Call `agentram_read_task_state` with `task_id`: `codex`.
+4. Summarize current goal, current task, and recent memory notes.

package/.claude/commands/ram.md

@@ -0,0 +1,14 @@
+---
+description: Retrieve AgentRAM context before coding.
+argument-hint: [query]
+---
+
+Use AgentRAM before coding.
+
+1. Call MCP tool `agentram_retrieve` with:
+   - `query`: `$ARGUMENTS`
+   - `task_id`: `codex`
+   - `limit`: `8`
+2. Read Goal Stack first.
+3. Use returned RAM notes as extra context.
+4. If no notes exist, continue normally and emit new events after important actions.

package/README.md

@@ -65,6 +65,12 @@ Equivalent explicit command:
 agentram tui
 ```
 
+Install Claude Code commands and subagents into the current project:
+
+```bash
+agentram claude-install --target .
+```
+
 Buttons inside the UI:
 
 ```text
@@ -153,6 +159,66 @@ If `python` is not the right binary, set `PYTHON`:
 ```bash
 PYTHON=python3 npx agentram status
 ```
+
+## Coding TUI, Slash Commands, And Subagents
+
+AgentRAM TUI now behaves like a coding-agent CLI inspired by `freecodexyz/free-code`: left status panel, chat transcript, slash command registry, RAM tool calls, and Claude subagent prompt templates.
+
+Run TUI:
+
+```bash
+agentram tui
+```
+
+Supported TUI slash commands:
+
+```text
+/help
+/init
+/status
+/retrieve <query>
+/goal
+/set-goal current_goal="Ship CLI" current_task="Add slash commands"
+/drift <task>
+/events
+/replay
+/agents
+/agent reviewer <task>
+/claude-install .
+/note <decision>
+/clear
+/exit
+```
+
+Claude Code repo templates are included:
+
+```text
+.claude/commands/ram.md
+.claude/commands/ram-drift.md
+.claude/commands/ram-note.md
+.claude/commands/ram-status.md
+.claude/agents/agentram-memory.md
+.claude/agents/agentram-planner.md
+.claude/agents/agentram-reviewer.md
+.claude/agents/agentram-docs.md
+```
+
+Usage inside Claude Code:
+
+```text
+/ram adapter memory writer
+/ram-drift refactor MCP server
+/ram-note Use npm wrapper only as Python launcher.
+/ram-status
+```
+
+Subagent intent:
+
+- `agentram-memory`: records durable notes, no code edits.
+- `agentram-planner`: checks Goal Stack and plans work.
+- `agentram-reviewer`: reviews changes against RAM and goal drift.
+- `agentram-docs`: updates docs from repo state and RAM notes.
+
 ## Install In Coding Agents
 
 ### Codex MCP
@@ -286,6 +352,53 @@ Minimum usage pattern:
 3. Call `agentram_check_goal_drift` before switching direction.
 4. Call `agentram_retrieve` again near context pressure or resume.
 
+
+## Multi-Model Coding Orchestration
+
+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 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
+```
+
+Build a dry-run orchestration plan:
+
+```bash
+agentram orchestrate "review CLI orchestration" --file agentram/cli.py
+```
+
+Run endpoints concurrently when keys and base URLs are configured:
+
+```bash
+agentram orchestrate "review CLI orchestration" --file agentram/cli.py --execute
+```
+
+Claude/MCP tools:
+
+```text
+agentram_bind_coding_model
+agentram_read_coding_models
+agentram_build_coding_orchestration
+agentram_run_coding_orchestration
+```
+
+TUI slash commands:
+
+```text
+/bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY
+/models
+/orchestrate review CLI orchestration
+```
+
+Storage:
+
+```text
+.agentram/agent_profile.json
+```
+
 ## MCP Tools
 
 | Tool | Purpose |
@@ -298,6 +411,10 @@ Minimum usage pattern:
 | `agentram_read_goal_state` | Read mission, goals, current task, histories. |
 | `agentram_update_goal_state` | Update Goal Stack fields. |
 | `agentram_check_goal_drift` | Warn only when task appears off-goal. |
+| `agentram_bind_coding_model` | Bind provider/model/role/modalities endpoint. |
+| `agentram_read_coding_models` | Read bound coding model endpoints. |
+| `agentram_build_coding_orchestration` | Build multi-agent prompts without model calls. |
+| `agentram_run_coding_orchestration` | Dry-run or execute endpoints concurrently. |
 
 ### Init
 

package/agentram/__init__.py

@@ -1,6 +1,7 @@
 from .adapter import AnthropicMemoryAdapter, HeuristicMemoryAdapter, OllamaMemoryAdapter, OpenAICompatibleMemoryAdapter
 from .config import anthropic_from_env, load_env_file, merged_env, openai_compatible_from_env
 from .daemon import AgentRAMDaemon
+from .orchestration import AgentModelEndpoint, CodingOrchestrationRequest, MultiModelCodingOrchestrator
 from .orchestrator import AgentRAM
 from .retriever import MemoryRetriever
 from .schema import Event, EventType, MemoryItem, MemoryPatch, MemoryScope, MemoryType
@@ -8,6 +9,8 @@ from .schema import Event, EventType, MemoryItem, MemoryPatch, MemoryScope, Memo
 __all__ = [
     "AgentRAM",
     "AgentRAMDaemon",
+    "AgentModelEndpoint",
+    "CodingOrchestrationRequest",
     "AnthropicMemoryAdapter",
     "anthropic_from_env",
     "Event",
@@ -20,6 +23,7 @@ __all__ = [
     "MemoryRetriever",
     "MemoryScope",
     "MemoryType",
+    "MultiModelCodingOrchestrator",
     "OllamaMemoryAdapter",
     "openai_compatible_from_env",
     "OpenAICompatibleMemoryAdapter",