agentram 0.1.1 → 0.1.2

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/README.md

@@ -352,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 |
@@ -364,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",

package/agentram/cli.py

@@ -30,6 +30,9 @@ SLASH_HELP = """Slash commands:
 /replay                       Replay events into memory
 /agents                       List subagent presets
 /agent <name> <task>          Build Claude Code subagent prompt
+/models                       List bound coding models
+/bind-model provider model    Bind model endpoint
+/orchestrate <task>           Build multi-model agent plan
 /claude-install [path]        Install .claude commands and agents
 /note <text>                  Save decision note
 /clear                        Clear chat
@@ -48,6 +51,20 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("status", help="Show RAM file and item counts.")
     subparsers.add_parser("goal", help="Show goal stack.")
     subparsers.add_parser("agents", help="List subagent presets.")
+    subparsers.add_parser("models", help="List bound coding model endpoints.")
+
+    bind_model = subparsers.add_parser("bind-model", help="Bind a coding model endpoint.")
+    bind_model.add_argument("provider", help="Provider name, e.g. claude, openai-compatible, groq.")
+    bind_model.add_argument("model", help="Model name.")
+    bind_model.add_argument("--role", default="coder", help="Agent role.")
+    bind_model.add_argument("--base-url", default="", help="Provider base URL.")
+    bind_model.add_argument("--api-key-env", default="", help="Environment variable containing API key.")
+    bind_model.add_argument("--modalities", default="text", help="Comma-separated modalities.")
+
+    orchestrate = subparsers.add_parser("orchestrate", help="Build or run multi-model coding orchestration.")
+    orchestrate.add_argument("task", nargs="?", default="", help="Coding task.")
+    orchestrate.add_argument("--file", action="append", default=[], help="File path to include.")
+    orchestrate.add_argument("--execute", action="store_true", help="Call model endpoints concurrently.")
 
     retrieve = subparsers.add_parser("retrieve", help="Retrieve memory context.")
     retrieve.add_argument("query", nargs="?", default="", help="Search query.")
@@ -111,6 +128,16 @@ def run_command(args: argparse.Namespace) -> int:
     if command == "agents":
         print(agents_text())
         return 0
+    if command == "models":
+        print(models_text(context))
+        return 0
+    if command == "bind-model":
+        print(bind_model_text(context, vars(args)))
+        return 0
+    if command == "orchestrate":
+        task = args.task or input("Task > ").strip()
+        print(orchestrate_text(context, task, files=args.file, execute=args.execute))
+        return 0
     if command == "claude-install":
         print(install_claude_templates_text(Path(args.target), force=args.force))
         return 0
@@ -182,6 +209,19 @@ def handle_slash_command(context: McpContext, text: str, messages: list[str] | N
         return replay_text(context, {})
     if command == "/agents":
         return agents_text()
+    if command == "/models":
+        return models_text(context)
+    if command == "/bind-model":
+        if len(rest) < 2:
+            return "Usage: /bind-model <provider> <model> [role=coder] [base_url=...] [api_key_env=...] [modalities=text,image]"
+        options = {"provider": rest[0], "model": rest[1]}
+        for item in rest[2:]:
+            if "=" in item:
+                key, value = item.split("=", 1)
+                options[key.replace("-", "_")] = value
+        return bind_model_text(context, options)
+    if command == "/orchestrate":
+        return orchestrate_text(context, raw_rest, execute=False)
     if command == "/agent":
         if not rest:
             return "Usage: /agent <memory|planner|reviewer|documenter> <task>"
@@ -298,6 +338,55 @@ def agent_prompt_text(context: McpContext, name: str, task: str) -> str:
 
 
 
+
+def models_text(context: McpContext) -> str:
+    data = payload(call_tool(context, "agentram_read_coding_models", {}))
+    endpoints = data.get("endpoints", [])
+    if not endpoints:
+        return "No coding models bound. Use /bind-model claude claude-3-5-sonnet-latest role=reviewer api_key_env=ANTHROPIC_API_KEY"
+    lines = ["Bound coding models:"]
+    for endpoint in endpoints:
+        lines.append(f"- {endpoint.get('id')} provider={endpoint.get('provider')} model={endpoint.get('model')} role={endpoint.get('role')} modalities={','.join(endpoint.get('modalities', []))}")
+    return "\n".join(lines)
+
+
+def bind_model_text(context: McpContext, options: dict[str, object]) -> str:
+    modalities_value = str(options.get("modalities", "text"))
+    arguments = {
+        "id": str(options.get("id", "")) or None,
+        "provider": str(options.get("provider", "openai-compatible")),
+        "model": str(options.get("model", "")),
+        "role": str(options.get("role", "coder")),
+        "base_url": str(options.get("base_url", "")),
+        "api_key_env": str(options.get("api_key_env", "")),
+        "modalities": [item.strip() for item in modalities_value.split(",") if item.strip()],
+        "enabled": bool(options.get("enabled", True)),
+    }
+    arguments = {key: value for key, value in arguments.items() if value is not None}
+    data = payload(call_tool(context, "agentram_bind_coding_model", arguments))
+    endpoint = data.get("endpoint", {})
+    return f"Bound model: {endpoint.get('id')} provider={endpoint.get('provider')} model={endpoint.get('model')} role={endpoint.get('role')}"
+
+
+def orchestrate_text(context: McpContext, task: str, files: list[str] | None = None, execute: bool = False) -> str:
+    if not task.strip():
+        return "Usage: /orchestrate <coding task>"
+    tool = "agentram_run_coding_orchestration" if execute else "agentram_build_coding_orchestration"
+    data = payload(call_tool(context, tool, {"task": task, "files": files or [], "execute": execute}))
+    if not execute:
+        lines = [f"Orchestration plan: agents={data.get('agent_count', 0)}"]
+        for agent in data.get("agents", []):
+            endpoint = agent.get("endpoint", {})
+            lines.append(f"- {endpoint.get('id')} {endpoint.get('provider')}:{endpoint.get('model')} role={endpoint.get('role')}")
+        return "\n".join(lines)
+    lines = [f"Orchestration run: agents={data.get('agent_count', 0)}"]
+    for result in data.get("results", []):
+        endpoint = result.get("endpoint", {})
+        status = "ok" if result.get("ok") else "error"
+        output = result.get("output") or result.get("error", "")
+        lines.append(f"- {endpoint.get('id')} {status}: {str(output)[:300]}")
+    return "\n".join(lines)
+
 def claude_template_root() -> Path:
     return Path(__file__).resolve().parent.parent / ".claude"
 
@@ -413,8 +502,9 @@ def sidebar_lines(context: McpContext) -> list[str]:
         "",
         "CLAUDE",
         "  /claude-install .",
-        "  /agents",
-        "  /agent reviewer <task>",
+        "  /models",
+        "  /bind-model claude <model>",
+        "  /orchestrate <task>",
     ]
 
 

package/agentram/mcp_server.py

@@ -11,9 +11,10 @@ from typing import Any
 from .adapter import HeuristicMemoryAdapter
 from .config import default_ram_root
 from .merger import MemoryMerger
+from .orchestration import AgentModelEndpoint, CodingOrchestrationRequest, MultiModelCodingOrchestrator
 from .retriever import MemoryRetriever
 from .schema import Event, EventType
-from .storage import JsonGoalStore, JsonMemoryStore, JsonlEventLog, ensure_ram_storage
+from .storage import JsonAgentProfileStore, JsonGoalStore, JsonMemoryStore, JsonlEventLog, ensure_ram_storage
 
 JSONRPC_VERSION = "2.0"
 SERVER_NAME = "agentram"
@@ -43,6 +44,10 @@ class McpContext:
     def goal_store(self) -> JsonGoalStore:
         return JsonGoalStore(self.ram_root / "goal_state.json")
 
+    @property
+    def profile_store(self) -> JsonAgentProfileStore:
+        return JsonAgentProfileStore(self.ram_root / "agent_profile.json")
+
     @property
     def merger(self) -> MemoryMerger:
         return MemoryMerger(self.memory_store)
@@ -220,6 +225,60 @@ def tools_list() -> dict[str, Any]:
                     },
                 },
             },
+
+            {
+                "name": "agentram_bind_coding_model",
+                "description": "Bind a coding-agent model endpoint that Claude or other agents can orchestrate later.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "provider": {"type": "string", "default": "openai-compatible"},
+                        "model": {"type": "string"},
+                        "role": {"type": "string", "default": "coder"},
+                        "base_url": {"type": "string"},
+                        "api_key_env": {"type": "string"},
+                        "modalities": {"type": "array", "items": {"type": "string"}},
+                        "enabled": {"type": "boolean", "default": True},
+                    },
+                    "required": ["provider", "model"],
+                },
+            },
+            {
+                "name": "agentram_read_coding_models",
+                "description": "Read coding-agent model endpoints bound to this project RAM.",
+                "inputSchema": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "agentram_build_coding_orchestration",
+                "description": "Build prompts for all enabled coding model endpoints without calling models.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "task": {"type": "string"},
+                        "query": {"type": "string"},
+                        "files": {"type": "array", "items": {"type": "string"}},
+                        "modalities": {"type": "array", "items": {"type": "string"}},
+                    },
+                    "required": ["task"],
+                },
+            },
+            {
+                "name": "agentram_run_coding_orchestration",
+                "description": "Run enabled coding model endpoints concurrently when execute=true, otherwise return dry-run plan.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "task": {"type": "string"},
+                        "query": {"type": "string"},
+                        "files": {"type": "array", "items": {"type": "string"}},
+                        "modalities": {"type": "array", "items": {"type": "string"}},
+                        "execute": {"type": "boolean", "default": False},
+                        "max_workers": {"type": "integer", "default": 4},
+                    },
+                    "required": ["task"],
+                },
+            },
             {
                 "name": "agentram_check_goal_drift",
                 "description": "Check whether a proposed task aligns with the current Goal Stack. Returns no suggestions when aligned.",
@@ -284,6 +343,32 @@ def call_tool(context: McpContext, name: str, arguments: dict[str, Any]) -> dict
         state = context.goal_store.update(arguments)
         return tool_result({"ok": True, "goal_state": state.to_dict(), "context": state.context_block()})
 
+
+    if name == "agentram_bind_coding_model":
+        endpoint = AgentModelEndpoint.from_dict(arguments)
+        data = context.profile_store.upsert(endpoint)
+        return tool_result({"ok": True, "endpoint": endpoint.to_dict(), "profile": data})
+
+    if name == "agentram_read_coding_models":
+        endpoints = context.profile_store.list_endpoints()
+        return tool_result({"endpoints": [endpoint.to_dict() for endpoint in endpoints]})
+
+    if name == "agentram_build_coding_orchestration":
+        request = orchestration_request_from_args(context, arguments)
+        endpoints = context.profile_store.list_endpoints()
+        plan = MultiModelCodingOrchestrator(endpoints).build_plan(request)
+        return tool_result({"ok": True, "execute": False, **plan})
+
+    if name == "agentram_run_coding_orchestration":
+        request = orchestration_request_from_args(context, arguments)
+        endpoints = context.profile_store.list_endpoints()
+        orchestrator = MultiModelCodingOrchestrator(endpoints)
+        if not bool(arguments.get("execute", False)):
+            plan = orchestrator.build_plan(request)
+            return tool_result({"ok": True, "execute": False, **plan})
+        result = orchestrator.run(request, max_workers=int(arguments.get("max_workers", 4)))
+        return tool_result({"ok": True, "execute": True, **result})
+
     if name == "agentram_check_goal_drift":
         task = str(arguments.get("task", ""))
         if not task.strip():
@@ -293,6 +378,27 @@ def call_tool(context: McpContext, name: str, arguments: dict[str, Any]) -> dict
     raise ValueError(f"unknown tool: {name}")
 
 
+
+def orchestration_request_from_args(context: McpContext, arguments: dict[str, Any]) -> CodingOrchestrationRequest:
+    task = str(arguments.get("task", ""))
+    if not task.strip():
+        raise ValueError("task is required")
+    query = str(arguments.get("query") or task)
+    files = arguments.get("files", [])
+    modalities = arguments.get("modalities", ["text"])
+    if not isinstance(files, list):
+        raise ValueError("files must be an array")
+    if not isinstance(modalities, list):
+        raise ValueError("modalities must be an array")
+    retriever = MemoryRetriever(context.memory_store, context.goal_store)
+    context_block = retriever.context_block(query=query, task_id="codex", limit=8)
+    return CodingOrchestrationRequest(
+        task=task,
+        context=context_block,
+        files=[str(item) for item in files],
+        modalities=[str(item) for item in modalities],
+    )
+
 def handle_request(context: McpContext, request: dict[str, Any]) -> dict[str, Any] | None:
     request_id = request.get("id")
     method = request.get("method")

package/agentram/orchestration.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+import json
+import os
+import urllib.request
+from typing import Any, Callable
+from uuid import uuid4
+
+
+@dataclass(frozen=True)
+class AgentModelEndpoint:
+    provider: str
+    model: str
+    role: str = "coder"
+    base_url: str = ""
+    api_key_env: str = ""
+    modalities: list[str] = field(default_factory=lambda: ["text"])
+    enabled: bool = True
+    id: str = field(default_factory=lambda: f"model_{uuid4().hex[:10]}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "provider": self.provider,
+            "model": self.model,
+            "role": self.role,
+            "base_url": self.base_url,
+            "api_key_env": self.api_key_env,
+            "modalities": self.modalities,
+            "enabled": self.enabled,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AgentModelEndpoint":
+        return cls(
+            id=str(data.get("id") or f"model_{uuid4().hex[:10]}"),
+            provider=str(data.get("provider", "openai-compatible")),
+            model=str(data.get("model", "")),
+            role=str(data.get("role", "coder")),
+            base_url=str(data.get("base_url", "")),
+            api_key_env=str(data.get("api_key_env", "")),
+            modalities=[str(item) for item in data.get("modalities", ["text"])],
+            enabled=bool(data.get("enabled", True)),
+        )
+
+
+@dataclass(frozen=True)
+class CodingOrchestrationRequest:
+    task: str
+    context: str = ""
+    files: list[str] = field(default_factory=list)
+    modalities: list[str] = field(default_factory=lambda: ["text"])
+
+    def to_prompt(self, endpoint: AgentModelEndpoint) -> str:
+        return "\n".join(
+            [
+                f"You are AgentRAM {endpoint.role} agent.",
+                f"Model: {endpoint.model}",
+                f"Provider: {endpoint.provider}",
+                f"Modalities: {', '.join(endpoint.modalities)}",
+                "Task:",
+                self.task,
+                "Files:",
+                "\n".join(f"- {item}" for item in self.files) or "- none provided",
+                "AgentRAM Context:",
+                self.context or "No context provided.",
+                "Output contract:",
+                "- Return concise coding findings or patch plan.",
+                "- Mention files to inspect or change.",
+                "- Do not invent repo facts.",
+            ]
+        )
+
+
+class MultiModelCodingOrchestrator:
+    def __init__(self, endpoints: list[AgentModelEndpoint], client: Callable[[AgentModelEndpoint, str], str] | None = None) -> None:
+        self.endpoints = [endpoint for endpoint in endpoints if endpoint.enabled]
+        self.client = client or self._call_endpoint
+
+    def build_plan(self, request: CodingOrchestrationRequest) -> dict[str, Any]:
+        agents = []
+        for endpoint in self.endpoints:
+            agents.append({"endpoint": endpoint.to_dict(), "prompt": request.to_prompt(endpoint)})
+        return {"task": request.task, "agent_count": len(agents), "agents": agents}
+
+    def run(self, request: CodingOrchestrationRequest, max_workers: int = 4) -> dict[str, Any]:
+        results: list[dict[str, Any]] = []
+        if not self.endpoints:
+            return {"task": request.task, "agent_count": 0, "results": []}
+        with ThreadPoolExecutor(max_workers=max(1, min(max_workers, len(self.endpoints)))) as executor:
+            future_map = {executor.submit(self.client, endpoint, request.to_prompt(endpoint)): endpoint for endpoint in self.endpoints}
+            for future in as_completed(future_map):
+                endpoint = future_map[future]
+                try:
+                    output = future.result()
+                    results.append({"endpoint": endpoint.to_dict(), "ok": True, "output": output})
+                except Exception as error:  # noqa: BLE001 - agent boundary
+                    results.append({"endpoint": endpoint.to_dict(), "ok": False, "error": str(error)})
+        return {"task": request.task, "agent_count": len(self.endpoints), "results": results}
+
+    def _call_endpoint(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
+        provider = endpoint.provider.lower()
+        if provider in {"openai", "openai-compatible", "groq", "vllm", "lmstudio", "ollama-v1"}:
+            return self._call_openai_compatible(endpoint, prompt)
+        if provider in {"anthropic", "claude"}:
+            return self._call_anthropic(endpoint, prompt)
+        raise ValueError(f"Unsupported provider for execution: {endpoint.provider}")
+
+    def _call_openai_compatible(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
+        api_key = os.getenv(endpoint.api_key_env) if endpoint.api_key_env else ""
+        if not endpoint.base_url:
+            raise ValueError("base_url is required")
+        if endpoint.api_key_env and not api_key:
+            raise ValueError(f"missing API key env: {endpoint.api_key_env}")
+        payload = {"model": endpoint.model, "messages": [{"role": "user", "content": prompt}], "temperature": 0}
+        request = urllib.request.Request(
+            endpoint.base_url.rstrip("/") + "/chat/completions",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"} if api_key else {"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=120) as response:
+            data = json.loads(response.read().decode("utf-8"))
+        return str(data.get("choices", [{}])[0].get("message", {}).get("content", ""))
+
+    def _call_anthropic(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
+        api_key = os.getenv(endpoint.api_key_env) if endpoint.api_key_env else ""
+        if endpoint.api_key_env and not api_key:
+            raise ValueError(f"missing API key env: {endpoint.api_key_env}")
+        base_url = endpoint.base_url.rstrip("/") if endpoint.base_url else "https://api.anthropic.com/v1"
+        payload = {"model": endpoint.model, "max_tokens": 1024, "messages": [{"role": "user", "content": prompt}]}
+        request = urllib.request.Request(
+            base_url + "/messages",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json", "x-api-key": api_key, "anthropic-version": "2023-06-01"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=120) as response:
+            data = json.loads(response.read().decode("utf-8"))
+        content = data.get("content", [])
+        if content and isinstance(content, list):
+            return "\n".join(str(item.get("text", "")) for item in content if isinstance(item, dict))
+        return str(data)

package/agentram/storage.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from .orchestration import AgentModelEndpoint
 from .schema import Event, GoalState, MemoryItem, utc_now
 
 
@@ -74,6 +75,40 @@ class JsonGoalStore:
         return self.save(GoalState.from_dict(current))
 
 
+class JsonAgentProfileStore:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def load(self) -> dict[str, object]:
+        if not self.path.exists():
+            return {"updated_at": utc_now(), "endpoints": []}
+        return json.loads(self.path.read_text(encoding="utf-8"))
+
+    def save(self, endpoints: list[AgentModelEndpoint]) -> dict[str, object]:
+        payload = {"updated_at": utc_now(), "endpoints": [endpoint.to_dict() for endpoint in endpoints]}
+        self.path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+        return payload
+
+    def list_endpoints(self) -> list[AgentModelEndpoint]:
+        data = self.load()
+        return [AgentModelEndpoint.from_dict(item) for item in data.get("endpoints", []) if isinstance(item, dict)]
+
+    def upsert(self, endpoint: AgentModelEndpoint) -> dict[str, object]:
+        endpoints = self.list_endpoints()
+        replaced = False
+        updated: list[AgentModelEndpoint] = []
+        for current in endpoints:
+            if current.id == endpoint.id:
+                updated.append(endpoint)
+                replaced = True
+            else:
+                updated.append(current)
+        if not replaced:
+            updated.append(endpoint)
+        return self.save(updated)
+
+
 def ensure_ram_storage(root: str | Path) -> dict[str, object]:
     ram_root = Path(root)
     ram_root.mkdir(parents=True, exist_ok=True)
@@ -81,6 +116,7 @@ def ensure_ram_storage(root: str | Path) -> dict[str, object]:
     events_path = ram_root / "events.jsonl"
     memory_path = ram_root / "memory.json"
     goal_path = ram_root / "goal_state.json"
+    profile_path = ram_root / "agent_profile.json"
 
     created: list[str] = []
     if not events_path.exists():
@@ -92,6 +128,9 @@ def ensure_ram_storage(root: str | Path) -> dict[str, object]:
     if not goal_path.exists():
         JsonGoalStore(goal_path).save(GoalState())
         created.append("goal_state.json")
+    if not profile_path.exists():
+        JsonAgentProfileStore(profile_path).save([])
+        created.append("agent_profile.json")
 
     return {
         "ram_root": str(ram_root),
@@ -100,5 +139,6 @@ def ensure_ram_storage(root: str | Path) -> dict[str, object]:
             "events": str(events_path),
             "memory": str(memory_path),
             "goal_state": str(goal_path),
+            "agent_profile": str(profile_path),
         },
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentram",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Async, model-agnostic Working RAM for coding agents.",
   "license": "MIT",
   "homepage": "https://github.com/trancongnghia/AGENT_RAM#readme",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentram"
-version = "0.1.1"
+version = "0.1.2"
 description = "Async, model-agnostic RAM layer for agentic coding tools."
 readme = "README.md"
 license = "MIT"