agentram 0.1.0

package/agentram/codex_wrapper.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .adapter import HeuristicMemoryAdapter, OllamaMemoryAdapter
+from .config import anthropic_from_env, default_ram_root, env_value, merged_env, openai_compatible_from_env
+from .orchestrator import AgentRAM
+from .retriever import MemoryRetriever
+from .schema import Event, EventType
+from .storage import JsonGoalStore, JsonMemoryStore
+
+
+@dataclass(frozen=True)
+class WrapperResult:
+    prompt: str
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+def build_injected_prompt(user_prompt: str, context_block: str) -> str:
+    if not context_block:
+        return user_prompt
+    return (
+        "Relevant AgentRAM notes:\n"
+        "Use only when relevant. Prefer current files over RAM if conflict.\n\n"
+        f"{context_block}\n\n"
+        "User request:\n"
+        f"{user_prompt}"
+    )
+
+
+def create_adapter(kind: str, env: dict[str, str]):
+    if kind == "heuristic":
+        return HeuristicMemoryAdapter()
+    if kind == "ollama":
+        return OllamaMemoryAdapter(
+            model=env_value(env, "OLLAMA_MODEL", default="qwen2.5:7b") or "qwen2.5:7b",
+            host=env_value(env, "OLLAMA_HOST", default="http://localhost:11434") or "http://localhost:11434",
+            timeout_seconds=float(env_value(env, "AGENTRAM_TIMEOUT", default="120") or "120"),
+        )
+    if kind == "openai-compatible":
+        return openai_compatible_from_env()
+    if kind == "anthropic":
+        return anthropic_from_env()
+    raise ValueError(f"unknown adapter: {kind}")
+
+
+async def run_wrapper(
+    user_prompt: str,
+    *,
+    task_id: str = "codex",
+    ram_root: str | None = None,
+    adapter_kind: str = "heuristic",
+    command: list[str] | None = None,
+    prompt_as_arg: bool = False,
+    dry_run: bool = False,
+) -> WrapperResult:
+    merged = merged_env()
+    resolved_ram_root = Path(ram_root) if ram_root else default_ram_root()
+    store = JsonMemoryStore(resolved_ram_root / "memory.json")
+    goal_store = JsonGoalStore(resolved_ram_root / "goal_state.json")
+    context_block = MemoryRetriever(store, goal_store).context_block(user_prompt, task_id=task_id, limit=10)
+    injected_prompt = build_injected_prompt(user_prompt, context_block)
+
+    adapter = create_adapter(adapter_kind, merged)
+    ram = AgentRAM(root=resolved_ram_root, adapter=adapter)
+    await ram.start()
+    ram.emit(Event(type=EventType.USER_MESSAGE, payload={"content": user_prompt}, task_id=task_id))
+
+    stdout = ""
+    stderr = ""
+    returncode = 0
+    if dry_run or not command:
+        stdout = injected_prompt
+    else:
+        run_command = command + ([injected_prompt] if prompt_as_arg else [])
+        completed = subprocess.run(
+            run_command,
+            input=None if prompt_as_arg else injected_prompt,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            check=False,
+        )
+        stdout = completed.stdout or ""
+        stderr = completed.stderr or ""
+        returncode = completed.returncode
+        ram.emit(
+            Event(
+                type=EventType.TOOL_CALL,
+                payload={"command": command, "returncode": returncode},
+                task_id=task_id,
+            )
+        )
+        output = stdout.strip() or stderr.strip()
+        if output:
+            ram.emit(
+                Event(
+                    type=EventType.AGENT_MESSAGE,
+                    payload={"content": output[:4000]},
+                    task_id=task_id,
+                )
+            )
+
+    await ram.stop()
+    return WrapperResult(prompt=injected_prompt, stdout=stdout, stderr=stderr, returncode=returncode)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Inject AgentRAM context into Codex or another CLI command.")
+    parser.add_argument("prompt", help="User prompt to send to Codex/command.")
+    parser.add_argument("--task-id", default="codex", help="AgentRAM task id.")
+    parser.add_argument("--ram-root", default=None, help="AgentRAM storage root. Defaults to .agentram in the current project directory.")
+    parser.add_argument(
+        "--adapter",
+        choices=["heuristic", "ollama", "openai-compatible", "anthropic"],
+        default="heuristic",
+        help="Memory writer adapter.",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="Print injected prompt without running command.")
+    parser.add_argument("--prompt-as-arg", action="store_true", help="Append injected prompt as final command argument instead of stdin.")
+    return parser
+
+
+def split_command_args(argv: list[str] | None) -> tuple[list[str] | None, list[str]]:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if "--" not in args:
+        return args, []
+    separator_index = args.index("--")
+    return args[:separator_index], args[separator_index + 1:]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    parser_args, command = split_command_args(argv)
+    args = parser.parse_args(parser_args)
+    result = asyncio.run(
+        run_wrapper(
+            args.prompt,
+            task_id=args.task_id,
+            ram_root=args.ram_root,
+            adapter_kind=args.adapter,
+            command=command or None,
+            prompt_as_arg=args.prompt_as_arg,
+            dry_run=args.dry_run,
+        )
+    )
+    if result.stdout:
+        print(result.stdout, end="" if result.stdout.endswith("\n") else "\n")
+    if result.stderr:
+        print(result.stderr, file=sys.stderr, end="" if result.stderr.endswith("\n") else "\n")
+    return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/agentram/config.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .adapter import AnthropicMemoryAdapter, OpenAICompatibleMemoryAdapter
+
+DEFAULT_AGENT_MODEL_ENV_NAMES = (
+    "CODEX_MODEL",
+    "CODEX_DEFAULT_MODEL",
+    "CLAUDE_MODEL",
+    "CURSOR_MODEL",
+    "AGENT_MODEL",
+)
+
+
+DEFAULT_RAM_DIR_NAME = ".agentram"
+
+def default_ram_root(cwd: str | Path | None = None) -> Path:
+    base = Path.cwd() if cwd is None else Path(cwd)
+    return base / DEFAULT_RAM_DIR_NAME
+
+def load_env_file(path: str | Path = ".env") -> dict[str, str]:
+    env_path = Path(path)
+    if not env_path.exists():
+        return {}
+    values: dict[str, str] = {}
+    for line in env_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip('"').strip("'")
+    return values
+
+
+def merged_env(path: str | Path = ".env") -> dict[str, str]:
+    return {**os.environ, **load_env_file(path)}
+
+
+def env_value(env: dict[str, str], *names: str, default: str | None = None) -> str | None:
+    for name in names:
+        value = env.get(name)
+        if value:
+            return value
+    return default
+
+
+def openai_compatible_from_env(path: str | Path = ".env") -> OpenAICompatibleMemoryAdapter:
+    env = merged_env(path)
+    model = env_value(env, "AGENTRAM_MODEL", "Model", "MODEL", *DEFAULT_AGENT_MODEL_ENV_NAMES)
+    base_url = env_value(env, "OPENAI_BASE_URL", "BASE_URL")
+    api_key = env_value(env, "OPENAI_API_KEY", "API_KEY", "GROQ_API_KEY")
+    if not model:
+        raise ValueError(
+            "Missing model. Set AGENTRAM_MODEL, Model, MODEL, or current agent model env such as CODEX_MODEL in .env."
+        )
+    if not base_url:
+        raise ValueError("Missing base URL. Set OPENAI_BASE_URL or BASE_URL in .env.")
+    if not api_key:
+        raise ValueError("Missing API key. Set OPENAI_API_KEY, API_KEY, or GROQ_API_KEY in .env.")
+    return OpenAICompatibleMemoryAdapter(
+        model=model,
+        base_url=base_url,
+        api_key=api_key,
+        timeout_seconds=float(env_value(env, "AGENTRAM_TIMEOUT", default="120") or "120"),
+        use_response_format=(env_value(env, "AGENTRAM_RESPONSE_FORMAT", default="false") or "false").lower() == "true",
+    )
+
+
+def anthropic_from_env(path: str | Path = ".env") -> AnthropicMemoryAdapter:
+    env = merged_env(path)
+    model = env_value(env, "ANTHROPIC_MODEL", "CLAUDE_MODEL", "AGENTRAM_MODEL", "Model", "MODEL")
+    api_key = env_value(env, "ANTHROPIC_API_KEY")
+    base_url = env_value(env, "ANTHROPIC_BASE_URL", default="https://api.anthropic.com/v1")
+    if not model:
+        raise ValueError("Missing Anthropic model. Set ANTHROPIC_MODEL, CLAUDE_MODEL, AGENTRAM_MODEL, Model, or MODEL in .env.")
+    if not api_key:
+        raise ValueError("Missing Anthropic API key. Set ANTHROPIC_API_KEY in .env.")
+    return AnthropicMemoryAdapter(
+        model=model,
+        base_url=base_url or "https://api.anthropic.com/v1",
+        api_key=api_key,
+        timeout_seconds=float(env_value(env, "AGENTRAM_TIMEOUT", default="120") or "120"),
+        max_tokens=int(env_value(env, "AGENTRAM_MAX_TOKENS", default="512") or "512"),
+        anthropic_version=env_value(env, "ANTHROPIC_VERSION", default="2023-06-01") or "2023-06-01",
+    )

package/agentram/daemon.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .adapter import HeuristicMemoryAdapter
+from .config import default_ram_root
+from .merger import MemoryMerger
+from .schema import Event
+from .storage import JsonMemoryStore, JsonlEventLog
+
+
+@dataclass(frozen=True)
+class DaemonState:
+    offset: int = 0
+
+    def to_dict(self) -> dict[str, int]:
+        return {"offset": self.offset}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DaemonState":
+        return cls(offset=int(data.get("offset", 0)))
+
+
+class AgentRAMDaemon:
+    def __init__(self, ram_root: str | Path | None = None) -> None:
+        self.ram_root = Path(ram_root) if ram_root else default_ram_root()
+        self.event_log = JsonlEventLog(self.ram_root / "events.jsonl")
+        self.memory_store = JsonMemoryStore(self.ram_root / "memory.json")
+        self.state_path = self.ram_root / "daemon_state.json"
+        self.adapter = HeuristicMemoryAdapter()
+        self.merger = MemoryMerger(self.memory_store)
+
+    def load_state(self) -> DaemonState:
+        if not self.state_path.exists():
+            return DaemonState()
+        return DaemonState.from_dict(json.loads(self.state_path.read_text(encoding="utf-8")))
+
+    def save_state(self, state: DaemonState) -> None:
+        self.state_path.parent.mkdir(parents=True, exist_ok=True)
+        self.state_path.write_text(json.dumps(state.to_dict(), indent=2), encoding="utf-8")
+
+    def ingest_new_events(self, limit: int | None = None) -> dict[str, Any]:
+        state = self.load_state()
+        events = self.event_log.read_all()
+        new_events = events[state.offset:]
+        if limit is not None:
+            new_events = new_events[:limit]
+        patches = self.adapter.create_patches(new_events, self.memory_store.list_items())
+        memory_items = self.merger.apply(patches)
+        next_offset = state.offset + len(new_events)
+        self.save_state(DaemonState(offset=next_offset))
+        return {
+            "read_offset": state.offset,
+            "write_offset": next_offset,
+            "event_count": len(new_events),
+            "patch_count": len(patches),
+            "memory_count": len(memory_items),
+        }
+
+    def replay_all(self) -> dict[str, Any]:
+        events = self.event_log.read_all()
+        patches = self.adapter.create_patches(events, [])
+        memory_items = self.merger.apply(patches)
+        self.save_state(DaemonState(offset=len(events)))
+        return {
+            "write_offset": len(events),
+            "event_count": len(events),
+            "patch_count": len(patches),
+            "memory_count": len(memory_items),
+        }
+
+    def run_forever(self, interval_seconds: float = 1.0, once: bool = False) -> None:
+        while True:
+            result = self.ingest_new_events()
+            print(json.dumps(result, ensure_ascii=False), flush=True)
+            if once:
+                return
+            time.sleep(interval_seconds)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="AgentRAM background event ingestion daemon.")
+    parser.add_argument("--ram-root", default=None, help="AgentRAM storage root. Defaults to .agentram in the current project directory.")
+    parser.add_argument("--interval", type=float, default=1.0, help="Polling interval in seconds.")
+    parser.add_argument("--once", action="store_true", help="Ingest pending events once and exit.")
+    parser.add_argument("--replay-all", action="store_true", help="Replay all events and reset daemon offset.")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    daemon = AgentRAMDaemon(ram_root=args.ram_root)
+    if args.replay_all:
+        print(json.dumps(daemon.replay_all(), ensure_ascii=False))
+        return 0
+    daemon.run_forever(interval_seconds=args.interval, once=args.once)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/agentram/demo.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from .orchestrator import AgentRAM
+from .retriever import MemoryRetriever
+from .schema import Event, EventType
+
+
+async def async_main() -> None:
+    ram = AgentRAM(root=Path(".agentram_demo"))
+    await ram.start()
+    ram.emit(Event(type=EventType.USER_MESSAGE, payload={"content": "Build model-agnostic AgentRAM for Codex/Claude/Cursor."}))
+    ram.emit(Event(type=EventType.READ_FILE, payload={"path": "agentram/orchestrator.py"}))
+    ram.emit(Event(type=EventType.DECISION, payload={"content": "Use Event Log as source of truth and Memory Patch as model contract."}))
+    ram.emit(Event(type=EventType.WRITE_FILE, payload={"path": "agentram/schema.py", "summary": "added normalized memory schema"}))
+    await ram.stop()
+
+    retriever = MemoryRetriever(ram.memory_store)
+    print(retriever.context_block("AgentRAM schema orchestrator", limit=10))
+
+
+def main() -> None:
+    asyncio.run(async_main())
+
+
+if __name__ == "__main__":
+    main()