agentram 0.1.0

package/agentram/schema.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Literal
+from uuid import uuid4
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class EventType(str, Enum):
+    READ_FILE = "READ_FILE"
+    WRITE_FILE = "WRITE_FILE"
+    TOOL_CALL = "TOOL_CALL"
+    DECISION = "DECISION"
+    USER_MESSAGE = "USER_MESSAGE"
+    AGENT_MESSAGE = "AGENT_MESSAGE"
+
+
+class MemoryType(str, Enum):
+    DECISION = "decision"
+    FACT = "fact"
+    TASK_STATE = "task_state"
+    FILE_SUMMARY = "file_summary"
+    OPEN_QUESTION = "open_question"
+
+
+class MemoryScope(str, Enum):
+    SESSION = "session"
+    TASK = "task"
+    PROJECT = "project"
+
+
+@dataclass(frozen=True)
+class Event:
+    type: EventType
+    payload: dict[str, Any]
+    task_id: str = "default"
+    id: str = field(default_factory=lambda: f"evt_{uuid4().hex}")
+    created_at: str = field(default_factory=utc_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "task_id": self.task_id,
+            "type": self.type.value,
+            "payload": self.payload,
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Event":
+        return cls(
+            id=data["id"],
+            task_id=data.get("task_id", "default"),
+            type=EventType(data["type"]),
+            payload=dict(data.get("payload", {})),
+            created_at=data["created_at"],
+        )
+
+
+@dataclass(frozen=True)
+class MemoryItem:
+    type: MemoryType
+    content: str
+    source_events: list[str]
+    task_id: str = "default"
+    related_files: list[str] = field(default_factory=list)
+    confidence: float = 0.8
+    scope: MemoryScope = MemoryScope.TASK
+    id: str = field(default_factory=lambda: f"mem_{uuid4().hex}")
+    created_at: str = field(default_factory=utc_now)
+    updated_at: str = field(default_factory=utc_now)
+    expires_at: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "task_id": self.task_id,
+            "type": self.type.value,
+            "content": self.content,
+            "source_events": self.source_events,
+            "related_files": self.related_files,
+            "confidence": self.confidence,
+            "scope": self.scope.value,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "expires_at": self.expires_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MemoryItem":
+        return cls(
+            id=data["id"],
+            task_id=data.get("task_id", "default"),
+            type=MemoryType(data["type"]),
+            content=data["content"],
+            source_events=list(data.get("source_events", [])),
+            related_files=list(data.get("related_files", [])),
+            confidence=float(data.get("confidence", 0.8)),
+            scope=MemoryScope(data.get("scope", "task")),
+            created_at=data["created_at"],
+            updated_at=data.get("updated_at", data["created_at"]),
+            expires_at=data.get("expires_at"),
+        )
+
+
+@dataclass(frozen=True)
+class MemoryPatch:
+    op: Literal["upsert", "delete"]
+    item: MemoryItem | None = None
+    target_id: str | None = None
+
+
+@dataclass(frozen=True)
+class GoalTask:
+    title: str
+    status: str = "pending"
+    id: str = field(default_factory=lambda: f"task_{uuid4().hex}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "title": self.title, "status": self.status}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GoalTask":
+        return cls(id=str(data.get("id") or f"task_{uuid4().hex}"), title=str(data.get("title", "")), status=str(data.get("status", "pending")))
+
+@dataclass(frozen=True)
+class GoalNode:
+    title: str
+    status: str = "pending"
+    tasks: list[GoalTask] = field(default_factory=list)
+    id: str = field(default_factory=lambda: f"goal_{uuid4().hex}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "title": self.title, "status": self.status, "tasks": [task.to_dict() for task in self.tasks]}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GoalNode":
+        return cls(
+            id=str(data.get("id") or f"goal_{uuid4().hex}"),
+            title=str(data.get("title", "")),
+            status=str(data.get("status", "pending")),
+            tasks=[GoalTask.from_dict(item) for item in data.get("tasks", []) if isinstance(item, dict)],
+        )
+
+@dataclass(frozen=True)
+class Milestone:
+    title: str
+    status: str = "pending"
+    goals: list[GoalNode] = field(default_factory=list)
+    id: str = field(default_factory=lambda: f"mile_{uuid4().hex}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "title": self.title, "status": self.status, "goals": [goal.to_dict() for goal in self.goals]}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Milestone":
+        return cls(
+            id=str(data.get("id") or f"mile_{uuid4().hex}"),
+            title=str(data.get("title", "")),
+            status=str(data.get("status", "pending")),
+            goals=[GoalNode.from_dict(item) for item in data.get("goals", []) if isinstance(item, dict)],
+        )
+
+@dataclass(frozen=True)
+class DecisionRecord:
+    content: str
+    source_events: list[str] = field(default_factory=list)
+    confidence: float = 0.8
+    id: str = field(default_factory=lambda: f"dec_{uuid4().hex}")
+    created_at: str = field(default_factory=utc_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "content": self.content, "source_events": self.source_events, "confidence": self.confidence, "created_at": self.created_at}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DecisionRecord":
+        return cls(
+            id=str(data.get("id") or f"dec_{uuid4().hex}"),
+            content=str(data.get("content", "")),
+            source_events=list(data.get("source_events", [])),
+            confidence=float(data.get("confidence", 0.8)),
+            created_at=str(data.get("created_at") or utc_now()),
+        )
+
+@dataclass(frozen=True)
+class GoalState:
+    mission: str = ""
+    project_goal: str = ""
+    milestones: list[Milestone] = field(default_factory=list)
+    completed_milestones: list[str] = field(default_factory=list)
+    current_milestone: str = ""
+    current_goal: str = ""
+    current_task: str = ""
+    next_tasks: list[str] = field(default_factory=list)
+    goal_history: list[str] = field(default_factory=list)
+    decision_history: list[DecisionRecord] = field(default_factory=list)
+    updated_at: str = field(default_factory=utc_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "mission": self.mission,
+            "project_goal": self.project_goal,
+            "milestones": [milestone.to_dict() for milestone in self.milestones],
+            "completed_milestones": self.completed_milestones,
+            "current_milestone": self.current_milestone,
+            "current_goal": self.current_goal,
+            "current_task": self.current_task,
+            "next_tasks": self.next_tasks,
+            "goal_history": self.goal_history,
+            "decision_history": [decision.to_dict() for decision in self.decision_history],
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GoalState":
+        return cls(
+            mission=str(data.get("mission", "")),
+            project_goal=str(data.get("project_goal", "")),
+            milestones=[Milestone.from_dict(item) for item in data.get("milestones", []) if isinstance(item, dict)],
+            completed_milestones=[str(item) for item in data.get("completed_milestones", [])],
+            current_milestone=str(data.get("current_milestone", "")),
+            current_goal=str(data.get("current_goal", "")),
+            current_task=str(data.get("current_task", "")),
+            next_tasks=[str(item) for item in data.get("next_tasks", [])],
+            goal_history=[str(item) for item in data.get("goal_history", [])],
+            decision_history=[DecisionRecord.from_dict(item) for item in data.get("decision_history", []) if isinstance(item, dict)],
+            updated_at=str(data.get("updated_at") or utc_now()),
+        )
+
+    def context_block(self) -> str:
+        lines: list[str] = []
+        if self.mission:
+            lines.append(f"Mission: {self.mission}")
+        if self.project_goal:
+            lines.append(f"Project Goal: {self.project_goal}")
+        if self.current_milestone:
+            lines.append(f"Current Milestone: {self.current_milestone}")
+        if self.current_goal:
+            lines.append(f"Current Goal: {self.current_goal}")
+        if self.current_task:
+            lines.append(f"Current Task: {self.current_task}")
+        if self.next_tasks:
+            lines.append("Next Tasks: " + "; ".join(self.next_tasks[:8]))
+        if self.completed_milestones:
+            lines.append("Completed Milestones: " + "; ".join(self.completed_milestones[:8]))
+        if self.goal_history:
+            lines.append("Goal History: " + " -> ".join(self.goal_history[-8:]))
+        if self.decision_history:
+            lines.append("Decision History:")
+            lines.extend(f"- {decision.content}" for decision in self.decision_history[-8:])
+        if not lines:
+            return ""
+        return "AgentRAM Goal Stack:\n" + "\n".join(lines)

package/agentram/storage.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .schema import Event, GoalState, MemoryItem, utc_now
+
+
+class JsonlEventLog:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, event: Event) -> None:
+        with self.path.open("a", encoding="utf-8") as file:
+            file.write(json.dumps(event.to_dict(), ensure_ascii=False) + "\n")
+
+    def read_all(self) -> list[Event]:
+        if not self.path.exists():
+            return []
+        events: list[Event] = []
+        with self.path.open("r", encoding="utf-8") as file:
+            for line in file:
+                if line.strip():
+                    events.append(Event.from_dict(json.loads(line)))
+        return events
+
+
+class JsonMemoryStore:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def list_items(self) -> list[MemoryItem]:
+        if not self.path.exists():
+            return []
+        data = json.loads(self.path.read_text(encoding="utf-8"))
+        return [MemoryItem.from_dict(item) for item in data.get("items", [])]
+
+    def save_items(self, items: list[MemoryItem]) -> None:
+        payload = {
+            "updated_at": utc_now(),
+            "items": [item.to_dict() for item in items],
+        }
+        self.path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+class JsonGoalStore:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def load(self) -> GoalState:
+        if not self.path.exists():
+            return GoalState()
+        data = json.loads(self.path.read_text(encoding="utf-8"))
+        return GoalState.from_dict(data)
+
+    def save(self, state: GoalState) -> GoalState:
+        payload = state.to_dict()
+        payload["updated_at"] = utc_now()
+        self.path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+        return GoalState.from_dict(payload)
+
+    def update(self, patch: dict[str, object]) -> GoalState:
+        current = self.load().to_dict()
+        for key, value in patch.items():
+            if key == "decision_history" and isinstance(value, list):
+                current[key] = current.get(key, []) + value
+            elif key == "goal_history" and isinstance(value, list):
+                current[key] = current.get(key, []) + value
+            elif key in current:
+                current[key] = value
+        return self.save(GoalState.from_dict(current))
+
+
+def ensure_ram_storage(root: str | Path) -> dict[str, object]:
+    ram_root = Path(root)
+    ram_root.mkdir(parents=True, exist_ok=True)
+
+    events_path = ram_root / "events.jsonl"
+    memory_path = ram_root / "memory.json"
+    goal_path = ram_root / "goal_state.json"
+
+    created: list[str] = []
+    if not events_path.exists():
+        events_path.write_text("", encoding="utf-8")
+        created.append("events.jsonl")
+    if not memory_path.exists():
+        JsonMemoryStore(memory_path).save_items([])
+        created.append("memory.json")
+    if not goal_path.exists():
+        JsonGoalStore(goal_path).save(GoalState())
+        created.append("goal_state.json")
+
+    return {
+        "ram_root": str(ram_root),
+        "created": created,
+        "files": {
+            "events": str(events_path),
+            "memory": str(memory_path),
+            "goal_state": str(goal_path),
+        },
+    }

package/agentram/worker.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import asyncio
+
+from .adapter import MemoryModelAdapter
+from .merger import MemoryMerger
+from .schema import Event
+
+
+class MemoryWorker:
+    def __init__(
+        self,
+        queue: asyncio.Queue[Event],
+        adapter: MemoryModelAdapter,
+        merger: MemoryMerger,
+        batch_size: int = 8,
+    ) -> None:
+        self.queue = queue
+        self.adapter = adapter
+        self.merger = merger
+        self.batch_size = batch_size
+        self._running = False
+
+    async def run(self) -> None:
+        self._running = True
+        while self._running:
+            batch = [await self.queue.get()]
+            while len(batch) < self.batch_size:
+                try:
+                    batch.append(self.queue.get_nowait())
+                except asyncio.QueueEmpty:
+                    break
+            current = self.merger.store.list_items()
+            patches = self.adapter.create_patches(batch, current)
+            self.merger.apply(patches)
+            for _ in batch:
+                self.queue.task_done()
+
+    def stop(self) -> None:
+        self._running = False

package/agentram_daemon.py

@@ -0,0 +1,4 @@
+from agentram.daemon import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/agentram_mcp_server.py

@@ -0,0 +1,4 @@
+from agentram.mcp_server import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bin/agentram-mcp.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const existingPythonPath = process.env.PYTHONPATH || "";
+const env = {
+  ...process.env,
+  PYTHONPATH: existingPythonPath ? `${packageRoot}${path.delimiter}${existingPythonPath}` : packageRoot,
+};
+
+function run(command, args) {
+  return spawnSync(command, args, { stdio: "inherit", env });
+}
+
+let result = run(process.env.PYTHON || "python", ["-m", "agentram.mcp_server", ...process.argv.slice(2)]);
+if (result.error && process.platform === "win32") {
+  result = run("py", ["-3", "-m", "agentram.mcp_server", ...process.argv.slice(2)]);
+}
+if (result.error) {
+  console.error(`AgentRAM MCP failed to start Python: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 0);

package/bin/agentram.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const existingPythonPath = process.env.PYTHONPATH || "";
+const env = {
+  ...process.env,
+  PYTHONPATH: existingPythonPath ? `${packageRoot}${path.delimiter}${existingPythonPath}` : packageRoot,
+};
+
+function run(command, args) {
+  return spawnSync(command, args, { stdio: "inherit", env });
+}
+
+let result = run(process.env.PYTHON || "python", ["-m", "agentram.cli", ...process.argv.slice(2)]);
+if (result.error && process.platform === "win32") {
+  result = run("py", ["-3", "-m", "agentram.cli", ...process.argv.slice(2)]);
+}
+if (result.error) {
+  console.error(`AgentRAM failed to start Python: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 0);

package/codex_ram.py

@@ -0,0 +1,4 @@
+from agentram.codex_wrapper import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "agentram",
+  "version": "0.1.0",
+  "description": "Async, model-agnostic Working RAM for coding agents.",
+  "license": "MIT",
+  "homepage": "https://github.com/trancongnghia/AGENT_RAM#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trancongnghia/AGENT_RAM.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trancongnghia/AGENT_RAM/issues"
+  },
+  "keywords": [
+    "agent",
+    "memory",
+    "codex",
+    "claude",
+    "mcp",
+    "llm"
+  ],
+  "bin": {
+    "agentram": "bin/agentram.js",
+    "agentram-mcp": "bin/agentram-mcp.js"
+  },
+  "scripts": {
+    "agentram": "node bin/agentram.js",
+    "agentram:mcp": "node bin/agentram-mcp.js",
+    "test": "python -m pytest -q",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm test"
+  },
+  "files": [
+    "agentram/*.py",
+    "bin/*.js",
+    "agentram_mcp_server.py",
+    "agentram_daemon.py",
+    "codex_ram.py",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentram"
+version = "0.1.0"
+description = "Async, model-agnostic RAM layer for agentic coding tools."
+readme = "README.md"
+license = "MIT"
+authors = [{name = "AgentRAM contributors"}]
+keywords = ["agent", "memory", "codex", "mcp", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Software Development :: Libraries",
+]
+
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/your-org/agentram"
+Repository = "https://github.com/your-org/agentram"
+Issues = "https://github.com/your-org/agentram/issues"
+
+[project.scripts]
+agentram = "agentram.cli:main"
+agentram-demo = "agentram.demo:main"
+agentram-codex = "agentram.codex_wrapper:main"
+agentram-mcp = "agentram.mcp_server:main"
+agentram-daemon = "agentram.daemon:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]