agentram 0.1.0

package/agentram/mcp_server.py

@@ -0,0 +1,369 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+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 .retriever import MemoryRetriever
+from .schema import Event, EventType
+from .storage import JsonGoalStore, JsonMemoryStore, JsonlEventLog, ensure_ram_storage
+
+JSONRPC_VERSION = "2.0"
+SERVER_NAME = "agentram"
+SERVER_VERSION = "0.1.0"
+
+def env_flag(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+
+@dataclass(frozen=True)
+class McpContext:
+    ram_root: Path
+
+    @property
+    def memory_store(self) -> JsonMemoryStore:
+        return JsonMemoryStore(self.ram_root / "memory.json")
+
+    @property
+    def event_log(self) -> JsonlEventLog:
+        return JsonlEventLog(self.ram_root / "events.jsonl")
+
+    @property
+    def goal_store(self) -> JsonGoalStore:
+        return JsonGoalStore(self.ram_root / "goal_state.json")
+
+    @property
+    def merger(self) -> MemoryMerger:
+        return MemoryMerger(self.memory_store)
+
+    def init_storage(self) -> dict[str, object]:
+        return ensure_ram_storage(self.ram_root)
+
+    def ingest_events(self, events: list[Event]) -> dict[str, Any]:
+        current = self.memory_store.list_items()
+        patches = HeuristicMemoryAdapter().create_patches(events, current)
+        items = self.merger.apply(patches)
+        return {
+            "patch_count": len(patches),
+            "memory_count": len(items),
+            "patches": [
+                {
+                    "op": patch.op,
+                    "item": patch.item.to_dict() if patch.item else None,
+                    "target_id": patch.target_id,
+                }
+                for patch in patches
+            ],
+        }
+
+    def replay_events(self, task_id: str | None = None) -> dict[str, Any]:
+        events = self.event_log.read_all()
+        if task_id:
+            events = [event for event in events if event.task_id == task_id]
+        ingest = self.ingest_events(events)
+        return {"event_count": len(events), **ingest}
+
+
+def text_content(text: str) -> list[dict[str, str]]:
+    return [{"type": "text", "text": text}]
+
+
+def tool_result(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "content": text_content(json.dumps(payload, indent=2, ensure_ascii=False)),
+        "structuredContent": payload,
+    }
+
+def tokenize(text: str) -> set[str]:
+    cleaned = "".join(char.lower() if char.isalnum() else " " for char in text)
+    return {token for token in cleaned.split() if len(token) >= 3}
+
+
+def check_goal_drift(task: str, context: McpContext) -> dict[str, Any]:
+    state = context.goal_store.load()
+    anchors = [
+        state.mission,
+        state.project_goal,
+        state.current_milestone,
+        state.current_goal,
+        state.current_task,
+        " ".join(state.next_tasks),
+        " ".join(state.completed_milestones),
+        " ".join(state.goal_history[-8:]),
+        " ".join(decision.content for decision in state.decision_history[-8:]),
+    ]
+    goal_text = " ".join(anchor for anchor in anchors if anchor)
+    if not goal_text.strip():
+        return {
+            "status": "unknown",
+            "aligned": None,
+            "score": 0,
+            "reason": "No goal_state.json content yet.",
+            "warning": None,
+            "next_actions": ["Set mission, project_goal, current_goal, and current_task first."],
+        }
+
+    task_terms = tokenize(task)
+    goal_terms = tokenize(goal_text)
+    overlaps = sorted(task_terms & goal_terms)
+    score = len(overlaps)
+    if score > 0:
+        return {
+            "status": "ok",
+            "aligned": True,
+            "score": score,
+            "overlap_terms": overlaps[:20],
+            "reason": "Task overlaps existing goal stack.",
+            "warning": None,
+            "next_actions": [],
+        }
+
+    return {
+        "status": "drift_risk",
+        "aligned": False,
+        "score": 0,
+        "overlap_terms": [],
+        "reason": "Task has no lexical overlap with mission, project goal, current milestone, current goal, current task, history, or decisions.",
+        "warning": "Potential goal drift. Confirm scope change or update goal_state before continuing.",
+        "next_actions": ["Confirm task belongs to current goal stack.", "If intentional, call agentram_update_goal_state first."],
+    }
+
+
+
+def tools_list() -> dict[str, Any]:
+    return {
+        "tools": [
+            {
+                "name": "agentram_init",
+                "description": "Create project-local .agentram files without overwriting existing memory.",
+                "inputSchema": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "agentram_retrieve",
+                "description": "Retrieve relevant AgentRAM notes for a query and task_id.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string"},
+                        "task_id": {"type": "string", "default": "codex"},
+                        "limit": {"type": "integer", "default": 8, "minimum": 1, "maximum": 50},
+                    },
+                    "required": ["query"],
+                },
+            },
+            {
+                "name": "agentram_emit_event",
+                "description": "Append an AgentRAM event such as USER_MESSAGE, DECISION, READ_FILE, WRITE_FILE, TOOL_CALL, or AGENT_MESSAGE.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "type": {"type": "string", "enum": [event_type.value for event_type in EventType]},
+                        "payload": {"type": "object"},
+                        "task_id": {"type": "string", "default": "codex"},
+                        "ingest": {"type": "boolean", "default": True},
+                    },
+                    "required": ["type", "payload"],
+                },
+            },
+            {
+                "name": "agentram_replay_events",
+                "description": "Replay events.jsonl into normalized RAM notes using the local heuristic adapter.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "task_id": {"type": "string", "description": "Optional task id filter."},
+                    },
+                },
+            },
+            {
+                "name": "agentram_read_task_state",
+                "description": "Read all stored RAM items for a task_id.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "task_id": {"type": "string", "default": "codex"},
+                    },
+                },
+            },
+            {
+                "name": "agentram_read_goal_state",
+                "description": "Read project goal hierarchy, current task, goal history, and decision history.",
+                "inputSchema": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "agentram_update_goal_state",
+                "description": "Update project goal hierarchy fields to reduce goal drift.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "mission": {"type": "string"},
+                        "project_goal": {"type": "string"},
+                        "milestones": {"type": "array"},
+                        "completed_milestones": {"type": "array", "items": {"type": "string"}},
+                        "current_milestone": {"type": "string"},
+                        "current_goal": {"type": "string"},
+                        "current_task": {"type": "string"},
+                        "next_tasks": {"type": "array", "items": {"type": "string"}},
+                        "goal_history": {"type": "array", "items": {"type": "string"}},
+                        "decision_history": {"type": "array"}
+                    },
+                },
+            },
+            {
+                "name": "agentram_check_goal_drift",
+                "description": "Check whether a proposed task aligns with the current Goal Stack. Returns no suggestions when aligned.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "task": {"type": "string"},
+                    },
+                    "required": ["task"],
+                },
+            },
+        ]
+    }
+
+
+def call_tool(context: McpContext, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    if name == "agentram_init":
+        return tool_result({"ok": True, **context.init_storage()})
+
+    if name == "agentram_retrieve":
+        query = str(arguments.get("query", ""))
+        task_id = str(arguments.get("task_id", "codex"))
+        limit = int(arguments.get("limit", 8))
+        retriever = MemoryRetriever(context.memory_store, context.goal_store)
+        items = retriever.retrieve(query=query, task_id=task_id, limit=limit)
+        return tool_result(
+            {
+                "task_id": task_id,
+                "query": query,
+                "context": retriever.context_block(query=query, task_id=task_id, limit=limit),
+                "items": [item.to_dict() for item in items],
+            }
+        )
+
+    if name == "agentram_emit_event":
+        event_type = EventType(str(arguments["type"]))
+        payload = arguments.get("payload", {})
+        if not isinstance(payload, dict):
+            raise ValueError("payload must be an object")
+        task_id = str(arguments.get("task_id", "codex"))
+        event = Event(type=event_type, payload=payload, task_id=task_id)
+        context.event_log.append(event)
+        ingest_result = context.ingest_events([event]) if bool(arguments.get("ingest", True)) else None
+        return tool_result({"ok": True, "event": event.to_dict(), "ingest": ingest_result})
+
+    if name == "agentram_replay_events":
+        task_id = arguments.get("task_id")
+        if task_id is not None:
+            task_id = str(task_id)
+        return tool_result({"ok": True, **context.replay_events(task_id=task_id)})
+
+    if name == "agentram_read_task_state":
+        task_id = str(arguments.get("task_id", "codex"))
+        items = [item.to_dict() for item in context.memory_store.list_items() if item.task_id == task_id]
+        return tool_result({"task_id": task_id, "items": items})
+
+    if name == "agentram_read_goal_state":
+        state = context.goal_store.load()
+        return tool_result({"goal_state": state.to_dict(), "context": state.context_block()})
+
+    if name == "agentram_update_goal_state":
+        state = context.goal_store.update(arguments)
+        return tool_result({"ok": True, "goal_state": state.to_dict(), "context": state.context_block()})
+
+    if name == "agentram_check_goal_drift":
+        task = str(arguments.get("task", ""))
+        if not task.strip():
+            raise ValueError("task is required")
+        return tool_result({"task": task, **check_goal_drift(task, context)})
+
+    raise ValueError(f"unknown tool: {name}")
+
+
+def handle_request(context: McpContext, request: dict[str, Any]) -> dict[str, Any] | None:
+    request_id = request.get("id")
+    method = request.get("method")
+    params = request.get("params", {})
+
+    try:
+        if method == "initialize":
+            result = {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
+            }
+        elif method == "notifications/initialized":
+            return None
+        elif method == "tools/list":
+            result = tools_list()
+        elif method == "tools/call":
+            if not isinstance(params, dict):
+                raise ValueError("params must be an object")
+            name = str(params.get("name", ""))
+            arguments = params.get("arguments", {})
+            if not isinstance(arguments, dict):
+                raise ValueError("arguments must be an object")
+            result = call_tool(context, name, arguments)
+        elif method == "ping":
+            result = {}
+        else:
+            return error_response(request_id, -32601, f"method not found: {method}")
+        if request_id is None:
+            return None
+        return {"jsonrpc": JSONRPC_VERSION, "id": request_id, "result": result}
+    except Exception as error:  # noqa: BLE001 - JSON-RPC boundary
+        if request_id is None:
+            return None
+        return error_response(request_id, -32000, str(error))
+
+
+def error_response(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": JSONRPC_VERSION, "id": request_id, "error": {"code": code, "message": message}}
+
+
+def run_stdio(ram_root: str | None = None) -> None:
+    context = McpContext(ram_root=Path(ram_root) if ram_root else default_ram_root())
+    if env_flag("AGENTRAM_AUTO_INIT"):
+        context.init_storage()
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError as error:
+            response = error_response(None, -32700, str(error))
+        else:
+            response = handle_request(context, request)
+        if response is not None:
+            sys.stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="AgentRAM MCP stdio server.")
+    parser.add_argument("--ram-root", default=None, help="AgentRAM storage root. Defaults to .agentram in the current project directory.")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    run_stdio(ram_root=args.ram_root)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/agentram/merger.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from collections.abc import Iterable
+
+from .schema import MemoryItem, MemoryPatch, utc_now
+from .storage import JsonMemoryStore
+
+
+class MemoryValidator:
+    def validate(self, patch: MemoryPatch) -> bool:
+        if patch.op == "delete":
+            return bool(patch.target_id)
+        if patch.item is None:
+            return False
+        if not patch.item.content.strip():
+            return False
+        if not patch.item.source_events:
+            return False
+        return 0.0 <= patch.item.confidence <= 1.0
+
+
+class MemoryMerger:
+    def __init__(self, store: JsonMemoryStore, validator: MemoryValidator | None = None) -> None:
+        self.store = store
+        self.validator = validator or MemoryValidator()
+
+    def apply(self, patches: list[MemoryPatch]) -> list[MemoryItem]:
+        items = self.store.list_items()
+        by_id = {item.id: item for item in items}
+
+        for patch in patches:
+            if not self.validator.validate(patch):
+                continue
+            if patch.op == "delete" and patch.target_id:
+                by_id.pop(patch.target_id, None)
+                continue
+            if patch.item is None:
+                continue
+            duplicate = self._find_duplicate(by_id.values(), patch.item)
+            if duplicate:
+                by_id[duplicate.id] = self._merge_duplicate(duplicate, patch.item)
+            else:
+                by_id[patch.item.id] = patch.item
+
+        merged = list(by_id.values())
+        self.store.save_items(merged)
+        return merged
+
+    def _find_duplicate(self, items: Iterable[MemoryItem], incoming: MemoryItem) -> MemoryItem | None:
+        normalized = incoming.content.strip().lower()
+        for item in items:
+            if item.task_id == incoming.task_id and item.type == incoming.type and item.content.strip().lower() == normalized:
+                return item
+        return None
+
+    def _merge_duplicate(self, current: MemoryItem, incoming: MemoryItem) -> MemoryItem:
+        source_events = sorted(set(current.source_events + incoming.source_events))
+        related_files = sorted(set(current.related_files + incoming.related_files))
+        return replace(
+            current,
+            source_events=source_events,
+            related_files=related_files,
+            confidence=max(current.confidence, incoming.confidence),
+            updated_at=utc_now(),
+        )

package/agentram/orchestrator.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from .adapter import HeuristicMemoryAdapter, MemoryModelAdapter
+from .merger import MemoryMerger
+from .schema import Event
+from .storage import JsonMemoryStore, JsonlEventLog
+from .worker import MemoryWorker
+
+
+class AgentRAM:
+    def __init__(self, root: str | Path = ".agentram", adapter: MemoryModelAdapter | None = None) -> None:
+        self.root = Path(root)
+        self.event_log = JsonlEventLog(self.root / "events.jsonl")
+        self.memory_store = JsonMemoryStore(self.root / "memory.json")
+        self.queue: asyncio.Queue[Event] = asyncio.Queue()
+        self.merger = MemoryMerger(self.memory_store)
+        self.adapter = adapter or HeuristicMemoryAdapter()
+        self.worker = MemoryWorker(self.queue, self.adapter, self.merger)
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self.worker.run())
+
+    async def stop(self) -> None:
+        await self.queue.join()
+        self.worker.stop()
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    def emit(self, event: Event) -> None:
+        self.event_log.append(event)
+        self.queue.put_nowait(event)
+
+    def replay(self) -> None:
+        events = self.event_log.read_all()
+        patches = self.adapter.create_patches(events, [])
+        self.merger.apply(patches)

package/agentram/retriever.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from .schema import MemoryItem, MemoryType
+from .storage import JsonGoalStore, JsonMemoryStore
+
+
+class MemoryRetriever:
+    def __init__(self, store: JsonMemoryStore, goal_store: JsonGoalStore | None = None) -> None:
+        self.store = store
+        self.goal_store = goal_store
+
+    def retrieve(
+        self,
+        query: str,
+        task_id: str = "default",
+        limit: int = 8,
+        types: set[MemoryType] | None = None,
+    ) -> list[MemoryItem]:
+        terms = {term.lower() for term in query.replace("/", " ").replace("_", " ").split() if term}
+        candidates = [item for item in self.store.list_items() if item.task_id == task_id]
+        if types:
+            candidates = [item for item in candidates if item.type in types]
+        ranked = sorted(candidates, key=lambda item: self._score(item, terms), reverse=True)
+        return [item for item in ranked if self._score(item, terms) > 0][:limit]
+
+    def context_block(self, query: str, task_id: str = "default", limit: int = 8) -> str:
+        blocks: list[str] = []
+        if self.goal_store is not None:
+            goal_block = self.goal_store.load().context_block()
+            if goal_block:
+                blocks.append(goal_block)
+        items = self.retrieve(query=query, task_id=task_id, limit=limit)
+        if items:
+            lines = ["Relevant AgentRAM notes:"]
+            for item in items:
+                files = f" files={','.join(item.related_files)}" if item.related_files else ""
+                lines.append(f"- [{item.type.value} confidence={item.confidence:.2f}{files}] {item.content}")
+            blocks.append("\n".join(lines))
+        return "\n\n".join(blocks)
+
+    def _score(self, item: MemoryItem, terms: set[str]) -> float:
+        haystack = " ".join([item.content, " ".join(item.related_files), item.type.value]).lower()
+        lexical = sum(1 for term in terms if term in haystack)
+        priority = {
+            MemoryType.TASK_STATE: 1.0,
+            MemoryType.DECISION: 0.9,
+            MemoryType.OPEN_QUESTION: 0.8,
+            MemoryType.FILE_SUMMARY: 0.7,
+            MemoryType.FACT: 0.6,
+        }[item.type]
+        return lexical + priority + item.confidence