agentram 0.1.0

package/agentram/__init__.py

@@ -0,0 +1,26 @@
+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 .orchestrator import AgentRAM
+from .retriever import MemoryRetriever
+from .schema import Event, EventType, MemoryItem, MemoryPatch, MemoryScope, MemoryType
+
+__all__ = [
+    "AgentRAM",
+    "AgentRAMDaemon",
+    "AnthropicMemoryAdapter",
+    "anthropic_from_env",
+    "Event",
+    "EventType",
+    "HeuristicMemoryAdapter",
+    "load_env_file",
+    "merged_env",
+    "MemoryItem",
+    "MemoryPatch",
+    "MemoryRetriever",
+    "MemoryScope",
+    "MemoryType",
+    "OllamaMemoryAdapter",
+    "openai_compatible_from_env",
+    "OpenAICompatibleMemoryAdapter",
+]

package/agentram/adapter.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+import json
+import os
+import re
+import urllib.request
+
+from .schema import Event, EventType, MemoryItem, MemoryPatch, MemoryScope, MemoryType
+
+
+class MemoryModelAdapter(ABC):
+    @abstractmethod
+    def create_patches(self, events: list[Event], current: list[MemoryItem]) -> list[MemoryPatch]:
+        raise NotImplementedError
+
+
+
+
+class OllamaMemoryAdapter(MemoryModelAdapter):
+    def __init__(
+        self,
+        model: str = "qwen2.5:1.5b",
+        host: str = "http://localhost:11434",
+        timeout_seconds: float = 30.0,
+        client: Callable[[str], str] | None = None,
+    ) -> None:
+        self.model = model
+        self.host = host.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self.client = client or self._call_ollama
+
+    def create_patches(self, events: list[Event], current: list[MemoryItem]) -> list[MemoryPatch]:
+        if not events:
+            return []
+        prompt = self._build_prompt(events, current)
+        response_text = self.client(prompt)
+        data = self._parse_json(response_text)
+        return self._patches_from_data(data, events)
+
+    def _call_ollama(self, prompt: str) -> str:
+        payload = {
+            "model": self.model,
+            "prompt": prompt,
+            "stream": False,
+            "format": "json",
+            "options": {"temperature": 0.0, "num_predict": 512},
+        }
+        request = urllib.request.Request(
+            f"{self.host}/api/generate",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json", "User-Agent": "AgentRAM/0.1"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=self.timeout_seconds) as response:
+            body = json.loads(response.read().decode("utf-8"))
+        return str(body.get("response", ""))
+
+    def _build_prompt(self, events: list[Event], current: list[MemoryItem]) -> str:
+        contract = {
+            "patches": [
+                {
+                    "op": "upsert",
+                    "type": "decision|fact|task_state|file_summary|open_question",
+                    "content": "short factual note",
+                    "source_events": ["event id from input"],
+                    "related_files": ["optional/path.py"],
+                    "confidence": 0.8,
+                    "scope": "session|task|project",
+                }
+            ]
+        }
+        event_payload = [event.to_dict() for event in events]
+        current_payload = [item.to_dict() for item in current[-20:]]
+        return (
+            "You are AgentRAM memory writer. Convert events into normalized memory patches.\n"
+            "Rules: output only JSON, no markdown, no reasoning, no chain-of-thought. "
+            "Use only source_events from input events. Keep notes concise and factual. "
+            "Do not invent files or facts. Return empty patches if nothing important.\n"
+            f"Output schema example: {json.dumps(contract, ensure_ascii=False)}\n"
+            f"Events: {json.dumps(event_payload, ensure_ascii=False)}\n"
+            f"Current memory: {json.dumps(current_payload, ensure_ascii=False)}"
+        )
+
+    def _parse_json(self, text: str) -> dict[str, object]:
+        try:
+            parsed = json.loads(text)
+            return parsed if isinstance(parsed, dict) else {"patches": []}
+        except json.JSONDecodeError:
+            match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+            if not match:
+                return {"patches": []}
+            try:
+                parsed = json.loads(match.group(0))
+                return parsed if isinstance(parsed, dict) else {"patches": []}
+            except json.JSONDecodeError:
+                return {"patches": []}
+
+    def _patches_from_data(self, data: dict[str, object], events: list[Event]) -> list[MemoryPatch]:
+        event_ids = {event.id for event in events}
+        default_task_id = events[-1].task_id
+        patches_data = data.get("patches", [])
+        if not isinstance(patches_data, list):
+            return []
+
+        patches: list[MemoryPatch] = []
+        for patch_data in patches_data:
+            if not isinstance(patch_data, dict):
+                continue
+            op = patch_data.get("op")
+            if op == "delete":
+                target_id = patch_data.get("target_id")
+                if isinstance(target_id, str):
+                    patches.append(MemoryPatch(op="delete", target_id=target_id))
+                continue
+            if op != "upsert":
+                continue
+            item = self._item_from_patch(patch_data, event_ids, default_task_id)
+            if item:
+                patches.append(MemoryPatch(op="upsert", item=item))
+        return patches
+
+    def _item_from_patch(
+        self,
+        patch_data: dict[str, object],
+        event_ids: set[str],
+        default_task_id: str,
+    ) -> MemoryItem | None:
+        content = patch_data.get("content")
+        source_events = patch_data.get("source_events")
+        if not isinstance(content, str) or not content.strip():
+            return None
+        if not isinstance(source_events, list):
+            return None
+        clean_source_events = [event_id for event_id in source_events if isinstance(event_id, str) and event_id in event_ids]
+        if not clean_source_events:
+            return None
+
+        try:
+            memory_type = MemoryType(str(patch_data.get("type", "fact")))
+            scope = MemoryScope(str(patch_data.get("scope", "task")))
+        except ValueError:
+            return None
+
+        related_files = patch_data.get("related_files", [])
+        clean_related_files = [path for path in related_files if isinstance(path, str)] if isinstance(related_files, list) else []
+        confidence = patch_data.get("confidence", 0.7)
+        if not isinstance(confidence, int | float):
+            confidence = 0.7
+
+        return MemoryItem(
+            task_id=default_task_id,
+            type=memory_type,
+            content=content.strip(),
+            source_events=clean_source_events,
+            related_files=clean_related_files,
+            confidence=max(0.0, min(1.0, float(confidence))),
+            scope=scope,
+        )
+
+
+
+
+class OpenAICompatibleMemoryAdapter(OllamaMemoryAdapter):
+    def __init__(
+        self,
+        model: str,
+        base_url: str = "http://localhost:8000/v1",
+        api_key: str | None = None,
+        timeout_seconds: float = 30.0,
+        max_tokens: int = 512,
+        use_response_format: bool = True,
+        client: Callable[[dict[str, object]], str] | None = None,
+    ) -> None:
+        super().__init__(model=model, host=base_url, timeout_seconds=timeout_seconds)
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key if api_key is not None else os.getenv("OPENAI_API_KEY", "EMPTY")
+        self.max_tokens = max_tokens
+        self.use_response_format = use_response_format
+        self.openai_client = client or self._call_openai_compatible
+
+    def create_patches(self, events: list[Event], current: list[MemoryItem]) -> list[MemoryPatch]:
+        if not events:
+            return []
+        payload = self._build_chat_payload(events, current)
+        response_text = self.openai_client(payload)
+        data = self._parse_json(response_text)
+        return self._patches_from_data(data, events)
+
+    def _build_chat_payload(self, events: list[Event], current: list[MemoryItem]) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "model": self.model,
+            "messages": [
+                {
+                    "role": "system",
+                    "content": "You are AgentRAM memory writer. Output only JSON. No markdown, no reasoning, no chain-of-thought.",
+                },
+                {
+                    "role": "user",
+                    "content": self._build_prompt(events, current),
+                },
+            ],
+            "temperature": 0,
+            "max_tokens": self.max_tokens,
+        }
+        if self.use_response_format:
+            payload["response_format"] = {"type": "json_object"}
+        return payload
+
+    def _call_openai_compatible(self, payload: dict[str, object]) -> str:
+        request = urllib.request.Request(
+            f"{self.base_url}/chat/completions",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": "AgentRAM/0.1",
+                "Accept": "application/json",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=self.timeout_seconds) as response:
+            body = json.loads(response.read().decode("utf-8"))
+        choices = body.get("choices", [])
+        if not isinstance(choices, list) or not choices:
+            return ""
+        first_choice = choices[0]
+        if not isinstance(first_choice, dict):
+            return ""
+        message = first_choice.get("message", {})
+        if not isinstance(message, dict):
+            return ""
+        content = message.get("content", "")
+        return content if isinstance(content, str) else ""
+
+
+
+class AnthropicMemoryAdapter(OllamaMemoryAdapter):
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str = "https://api.anthropic.com/v1",
+        timeout_seconds: float = 30.0,
+        max_tokens: int = 512,
+        anthropic_version: str = "2023-06-01",
+        client: Callable[[dict[str, object]], str] | None = None,
+    ) -> None:
+        super().__init__(model=model, host=base_url, timeout_seconds=timeout_seconds)
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key if api_key is not None else os.getenv("ANTHROPIC_API_KEY", "")
+        self.max_tokens = max_tokens
+        self.anthropic_version = anthropic_version
+        self.anthropic_client = client or self._call_anthropic
+
+    def create_patches(self, events: list[Event], current: list[MemoryItem]) -> list[MemoryPatch]:
+        if not events:
+            return []
+        payload = self._build_messages_payload(events, current)
+        response_text = self.anthropic_client(payload)
+        data = self._parse_json(response_text)
+        return self._patches_from_data(data, events)
+
+    def _build_messages_payload(self, events: list[Event], current: list[MemoryItem]) -> dict[str, object]:
+        return {
+            "model": self.model,
+            "system": "You are AgentRAM memory writer. Output only JSON. No markdown, no reasoning, no chain-of-thought.",
+            "messages": [
+                {
+                    "role": "user",
+                    "content": self._build_prompt(events, current),
+                }
+            ],
+            "temperature": 0,
+            "max_tokens": self.max_tokens,
+        }
+
+    def _call_anthropic(self, payload: dict[str, object]) -> str:
+        request = urllib.request.Request(
+            f"{self.base_url}/messages",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "x-api-key": self.api_key,
+                "anthropic-version": self.anthropic_version,
+                "User-Agent": "AgentRAM/0.1",
+                "Accept": "application/json",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=self.timeout_seconds) as response:
+            body = json.loads(response.read().decode("utf-8"))
+        content = body.get("content", [])
+        if not isinstance(content, list):
+            return ""
+        parts: list[str] = []
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "text" and isinstance(block.get("text"), str):
+                parts.append(str(block["text"]))
+        return "\n".join(parts)
+
+
+class HeuristicMemoryAdapter(MemoryModelAdapter):
+    def create_patches(self, events: list[Event], current: list[MemoryItem]) -> list[MemoryPatch]:
+        patches: list[MemoryPatch] = []
+        for event in events:
+            item = self._event_to_item(event)
+            if item:
+                patches.append(MemoryPatch(op="upsert", item=item))
+        return patches
+
+    def _event_to_item(self, event: Event) -> MemoryItem | None:
+        payload = event.payload
+        if event.type == EventType.READ_FILE:
+            path = str(payload.get("path", ""))
+            if not path:
+                return None
+            return MemoryItem(
+                task_id=event.task_id,
+                type=MemoryType.FILE_SUMMARY,
+                content=f"Main agent opened file `{path}`.",
+                related_files=[path],
+                source_events=[event.id],
+                confidence=0.95,
+                scope=MemoryScope.TASK,
+            )
+        if event.type == EventType.WRITE_FILE:
+            path = str(payload.get("path", ""))
+            summary = str(payload.get("summary", "updated"))
+            if not path:
+                return None
+            return MemoryItem(
+                task_id=event.task_id,
+                type=MemoryType.FILE_SUMMARY,
+                content=f"Main agent changed `{path}`: {summary}.",
+                related_files=[path],
+                source_events=[event.id],
+                confidence=0.9,
+                scope=MemoryScope.TASK,
+            )
+        if event.type == EventType.DECISION:
+            content = str(payload.get("content", "")).strip()
+            if not content:
+                return None
+            return MemoryItem(
+                task_id=event.task_id,
+                type=MemoryType.DECISION,
+                content=content,
+                source_events=[event.id],
+                confidence=0.9,
+                scope=MemoryScope.TASK,
+            )
+        if event.type == EventType.USER_MESSAGE:
+            content = str(payload.get("content", "")).strip()
+            if not content:
+                return None
+            return MemoryItem(
+                task_id=event.task_id,
+                type=MemoryType.TASK_STATE,
+                content=f"User request: {content}",
+                source_events=[event.id],
+                confidence=0.85,
+                scope=MemoryScope.TASK,
+            )
+        return None

package/agentram/cli.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import textwrap
+from pathlib import Path
+from typing import Any
+
+from .config import default_ram_root
+from .mcp_server import McpContext, call_tool
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="AgentRAM terminal UI and CLI.")
+    parser.add_argument("--ram-root", default=None, help="AgentRAM storage root. Defaults to .agentram in the current project directory.")
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("tui", help="Open terminal chat UI.")
+    subparsers.add_parser("init", help="Create AgentRAM files.")
+    subparsers.add_parser("status", help="Show RAM file and item counts.")
+    subparsers.add_parser("goal", help="Show goal stack.")
+
+    retrieve = subparsers.add_parser("retrieve", help="Retrieve memory context.")
+    retrieve.add_argument("query", nargs="?", default="", help="Search query.")
+    retrieve.add_argument("--task-id", default="codex", help="Task id.")
+    retrieve.add_argument("--limit", type=int, default=8, help="Max items.")
+
+    drift = subparsers.add_parser("drift", help="Check goal drift for a task.")
+    drift.add_argument("task", nargs="?", default="", help="Task to check.")
+
+    replay = subparsers.add_parser("replay", help="Replay events into memory.")
+    replay.add_argument("--task-id", default=None, help="Optional task id filter.")
+
+    return parser
+
+
+def context_from_args(args: argparse.Namespace) -> McpContext:
+    ram_root = Path(args.ram_root) if args.ram_root else default_ram_root()
+    return McpContext(ram_root=ram_root)
+
+
+def payload(result: dict[str, Any]) -> dict[str, Any]:
+    return dict(result.get("structuredContent", {}))
+
+
+def print_status(context: McpContext) -> None:
+    context.init_storage()
+    memory_items = context.memory_store.list_items()
+    events = context.event_log.read_all()
+    goal_state = context.goal_store.load()
+    print(f"AgentRAM root: {context.ram_root}")
+    print(f"Events: {len(events)}")
+    print(f"Memory items: {len(memory_items)}")
+    print(f"Mission: {goal_state.mission or '-'}")
+    print(f"Current goal: {goal_state.current_goal or '-'}")
+    print(f"Current task: {goal_state.current_task or '-'}")
+
+
+def run_command(args: argparse.Namespace) -> int:
+    context = context_from_args(args)
+    command = args.command or "tui"
+
+    if command == "tui":
+        run_tui(context)
+        return 0
+    if command == "init":
+        data = payload(call_tool(context, "agentram_init", {}))
+        print(f"AgentRAM root: {data['ram_root']}")
+        created = data.get("created", [])
+        print("Created: " + (", ".join(created) if created else "none"))
+        return 0
+    if command == "status":
+        print_status(context)
+        return 0
+    if command == "retrieve":
+        query = args.query or input("Query > ").strip()
+        data = payload(call_tool(context, "agentram_retrieve", {"query": query, "task_id": args.task_id, "limit": args.limit}))
+        print(data.get("context") or "No matching memory.")
+        return 0
+    if command == "goal":
+        data = payload(call_tool(context, "agentram_read_goal_state", {}))
+        print(data.get("context") or "No goal stack yet.")
+        return 0
+    if command == "drift":
+        task = args.task or input("Task > ").strip()
+        data = payload(call_tool(context, "agentram_check_goal_drift", {"task": task}))
+        print(f"Status: {data.get('status')}")
+        print(f"Aligned: {data.get('aligned')}")
+        print(f"Reason: {data.get('reason')}")
+        if data.get("warning"):
+            print(f"Warning: {data['warning']}")
+        return 0
+    if command == "replay":
+        arguments = {"task_id": args.task_id} if args.task_id else {}
+        data = payload(call_tool(context, "agentram_replay_events", arguments))
+        print(f"Events: {data.get('event_count', 0)}")
+        print(f"Patches: {data.get('patch_count', 0)}")
+        print(f"Memory items: {data.get('memory_count', 0)}")
+        return 0
+
+    raise SystemExit(f"unknown command: {command}")
+
+
+def run_tui(context: McpContext) -> None:
+    context.init_storage()
+    messages = ["AgentRAM terminal UI ready.", f"RAM root: {context.ram_root}"]
+    while True:
+        draw_screen(context, messages)
+        choice = input("You > ").strip()
+        if choice in {"0", "q", "quit", "exit"}:
+            return
+        handle_tui_choice(context, choice, messages)
+
+
+def handle_tui_choice(context: McpContext, choice: str, messages: list[str]) -> None:
+    try:
+        if choice == "1":
+            data = payload(call_tool(context, "agentram_init", {}))
+            created = data.get("created", [])
+            messages.append("Init: " + (", ".join(created) if created else "already ready"))
+        elif choice == "2":
+            messages.append(status_text(context))
+        elif choice == "3":
+            query = input("Query > ").strip()
+            data = payload(call_tool(context, "agentram_retrieve", {"query": query, "task_id": "codex", "limit": 8}))
+            messages.append(data.get("context") or "No matching memory.")
+        elif choice == "4":
+            data = payload(call_tool(context, "agentram_read_goal_state", {}))
+            messages.append(data.get("context") or "No goal stack yet.")
+        elif choice == "5":
+            update_goal_from_prompt(context, messages)
+        elif choice == "6":
+            task = input("Task > ").strip()
+            data = payload(call_tool(context, "agentram_check_goal_drift", {"task": task}))
+            messages.append(f"Drift: {data.get('status')} | aligned={data.get('aligned')} | {data.get('reason')}")
+        elif choice == "7":
+            events = context.event_log.read_all()
+            latest = events[-5:]
+            lines = [f"Events: {len(events)}"]
+            lines.extend(f"- {event.type.value} {event.payload}" for event in latest)
+            messages.append("\n".join(lines))
+        elif choice == "8":
+            data = payload(call_tool(context, "agentram_replay_events", {}))
+            messages.append(f"Replay: events={data.get('event_count', 0)} patches={data.get('patch_count', 0)} memory={data.get('memory_count', 0)}")
+        elif choice == "9" or not choice:
+            messages.append("Choose button number. Use retrieve before injecting context into agent prompt.")
+        else:
+            messages.append(f"Unknown button: {choice}")
+    except Exception as error:  # noqa: BLE001 - terminal boundary
+        messages.append(f"Error: {error}")
+    del messages[:-8]
+
+
+def update_goal_from_prompt(context: McpContext, messages: list[str]) -> None:
+    patch: dict[str, object] = {}
+    fields = ["mission", "project_goal", "current_milestone", "current_goal", "current_task"]
+    for field in fields:
+        value = input(f"{field} (blank skip) > ").strip()
+        if value:
+            patch[field] = value
+    next_tasks = input("next_tasks comma list (blank skip) > ").strip()
+    if next_tasks:
+        patch["next_tasks"] = [item.strip() for item in next_tasks.split(",") if item.strip()]
+    if not patch:
+        messages.append("Goal update skipped.")
+        return
+    data = payload(call_tool(context, "agentram_update_goal_state", patch))
+    messages.append(data.get("context") or "Goal updated.")
+
+
+def status_text(context: McpContext) -> str:
+    context.init_storage()
+    events = context.event_log.read_all()
+    items = context.memory_store.list_items()
+    goal_state = context.goal_store.load()
+    return "\n".join(
+        [
+            f"RAM root: {context.ram_root}",
+            f"Events: {len(events)}",
+            f"Memory items: {len(items)}",
+            f"Current goal: {goal_state.current_goal or '-'}",
+            f"Current task: {goal_state.current_task or '-'}",
+        ]
+    )
+
+
+def draw_screen(context: McpContext, messages: list[str]) -> None:
+    clear_terminal()
+    width = min(max(shutil.get_terminal_size((100, 30)).columns, 72), 120)
+    print(box_line("┌", "─", "┐", width))
+    print(box_text("AgentRAM CLI", width))
+    print(box_text(f"root: {context.ram_root}", width))
+    print(box_line("├", "─", "┤", width))
+    for line in menu_lines():
+        print(box_text(line, width))
+    print(box_line("├", "─", "┤", width))
+    chat_lines = wrap_messages(messages, width - 4)
+    visible = chat_lines[-14:]
+    for line in visible:
+        print(box_text(line, width))
+    for _ in range(max(0, 14 - len(visible))):
+        print(box_text("", width))
+    print(box_line("└", "─", "┘", width))
+
+
+def menu_lines() -> list[str]:
+    return [
+        "[1] Init RAM        [2] Status          [3] Retrieve",
+        "[4] Goal Show       [5] Goal Set        [6] Drift Check",
+        "[7] Events          [8] Replay          [9] Help       [0] Exit",
+    ]
+
+
+def wrap_messages(messages: list[str], width: int) -> list[str]:
+    lines: list[str] = []
+    for message in messages:
+        for raw_line in str(message).splitlines() or [""]:
+            wrapped = textwrap.wrap(raw_line, width=width, replace_whitespace=False) or [""]
+            lines.extend(wrapped)
+    return lines
+
+
+def box_line(left: str, fill: str, right: str, width: int) -> str:
+    return left + fill * (width - 2) + right
+
+
+def box_text(text: str, width: int) -> str:
+    return "│ " + text[: width - 4].ljust(width - 4) + " │"
+
+
+def clear_terminal() -> None:
+    os.system("cls" if os.name == "nt" else "clear")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return run_command(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())