dial-memory 0.1.1__py3-none-any.whl

dial_memory/provider.py

@@ -0,0 +1,278 @@
+"""Dial — file-based MemoryProvider implementation."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from strawpot.memory.protocol import (
+    ContextCard,
+    ControlSignal,
+    DumpReceipt,
+    GetResult,
+    MemoryKind,
+    RememberResult,
+)
+
+from .scorer import score_and_filter
+from .storage import (
+    append_jsonl,
+    em_path,
+    expand_path,
+    knowledge_path,
+    read_jsonl,
+    read_jsonl_tail,
+    role_knowledge_path,
+)
+
+
+class DialMemoryProvider:
+    """Default file-based memory provider for StrawPot."""
+
+    name = "dial"
+
+    def __init__(self, config: dict | None = None):
+        cfg = config or {}
+        self._storage_dir = expand_path(
+            cfg.get("storage_dir", ".strawpot/memory/dial-data")
+        )
+        self._global_dir = expand_path(
+            cfg.get("global_storage_dir", "~/.strawpot/memory/dial-data")
+        )
+        self._em_tail_count: int = int(cfg.get("em_tail_count", 20))
+        self._em_max_events: int = int(cfg.get("em_max_events", 10000))
+        self._rm_min_score: float = float(cfg.get("rm_min_score", 0.3))
+
+    # -- get ------------------------------------------------------------------
+
+    def get(
+        self,
+        *,
+        session_id: str,
+        agent_id: str,
+        role: str,
+        behavior_ref: str,
+        task: str,
+        budget: int | None = None,
+        parent_agent_id: str | None = None,
+    ) -> GetResult:
+        cards: list[ContextCard] = []
+        sources: list[str] = []
+
+        # 1. Collect knowledge from all scopes
+        all_entries = self._collect_knowledge(role)
+
+        # 2. SM — entries without keywords (always included)
+        sm_entries = [e for e in all_entries if not e.get("keywords")]
+        if sm_entries:
+            cards.append(
+                ContextCard(
+                    kind=MemoryKind.SM,
+                    content=_format_knowledge(sm_entries),
+                    source="knowledge",
+                )
+            )
+            sources.append("sm")
+
+        # 3. RM — entries with keywords (conditionally included)
+        rm_entries = [e for e in all_entries if e.get("keywords")]
+        rm_matches = score_and_filter(rm_entries, task, self._rm_min_score)
+        if rm_matches:
+            cards.append(
+                ContextCard(
+                    kind=MemoryKind.RM,
+                    content=_format_knowledge(rm_matches),
+                    source="knowledge",
+                )
+            )
+            sources.append("rm")
+
+        # 4. EM — recent session events
+        em_events = read_jsonl_tail(
+            em_path(self._storage_dir, session_id), self._em_tail_count
+        )
+        if em_events:
+            cards.append(
+                ContextCard(
+                    kind=MemoryKind.EM,
+                    content=_format_em(em_events),
+                    source="em",
+                )
+            )
+            sources.append("em")
+
+        # 5. Budget trimming
+        if budget is not None:
+            cards = _trim_to_budget(cards, budget)
+
+        return GetResult(
+            context_cards=cards,
+            control_signals=ControlSignal(),
+            sources_used=sources,
+        )
+
+    # -- dump -----------------------------------------------------------------
+
+    def dump(
+        self,
+        *,
+        session_id: str,
+        agent_id: str,
+        role: str,
+        behavior_ref: str,
+        task: str,
+        status: str,
+        output: str,
+        tool_trace: str = "",
+        parent_agent_id: str | None = None,
+        artifacts: dict[str, str] | None = None,
+    ) -> DumpReceipt:
+        event_id = _make_id("evt")
+        event = {
+            "event_id": event_id,
+            "ts": _now_iso(),
+            "session_id": session_id,
+            "agent_id": agent_id,
+            "role": role,
+            "event_type": "AGENT_RESULT",
+            "data": {
+                "task": task,
+                "status": status,
+                "summary": output[:500] if output else "",
+            },
+        }
+        append_jsonl(em_path(self._storage_dir, session_id), event)
+        return DumpReceipt(em_event_ids=[event_id])
+
+    # -- remember -------------------------------------------------------------
+
+    def remember(
+        self,
+        *,
+        session_id: str,
+        agent_id: str,
+        role: str,
+        content: str,
+        keywords: list[str] | None = None,
+        scope: str = "project",
+    ) -> RememberResult:
+        kw = keywords or []
+        store_path = self._knowledge_store_path(scope, role)
+
+        # Dedup: exact content match
+        existing = read_jsonl(store_path)
+        for entry in existing:
+            if entry.get("content") == content:
+                return RememberResult(status="duplicate", entry_id=entry.get("entry_id", ""))
+
+        entry_id = _make_id("k")
+        entry = {
+            "entry_id": entry_id,
+            "content": content,
+            "keywords": kw,
+            "source": agent_id,
+            "ts": _now_iso(),
+        }
+        append_jsonl(store_path, entry)
+        return RememberResult(status="accepted", entry_id=entry_id)
+
+    # -- internal helpers -----------------------------------------------------
+
+    def _collect_knowledge(self, role: str) -> list[dict]:
+        """Merge knowledge from global, project, and role scopes; deduplicate."""
+        global_entries = read_jsonl(knowledge_path(self._global_dir))
+        project_entries = read_jsonl(knowledge_path(self._storage_dir))
+        role_entries = read_jsonl(role_knowledge_path(self._storage_dir, role))
+
+        all_entries = global_entries + project_entries + role_entries
+        return _deduplicate(all_entries)
+
+    def _knowledge_store_path(self, scope: str, role: str) -> Path:
+        """Return the knowledge.jsonl path for the given scope."""
+        if scope == "global":
+            return knowledge_path(self._global_dir)
+        elif scope == "role":
+            return role_knowledge_path(self._storage_dir, role)
+        else:  # "project" (default)
+            return knowledge_path(self._storage_dir)
+
+
+# -- Formatting helpers -------------------------------------------------------
+
+
+def _format_knowledge(entries: list[dict]) -> str:
+    """Format knowledge entries as readable text for context cards."""
+    lines = []
+    for e in entries:
+        lines.append(f"- {e['content']}")
+    return "\n".join(lines)
+
+
+def _format_em(events: list[dict]) -> str:
+    """Format EM events as readable text for context cards."""
+    lines = []
+    for ev in events:
+        data = ev.get("data", {})
+        role = ev.get("role", "")
+        status = data.get("status", "")
+        task = data.get("task", "")
+        summary = data.get("summary", "")
+        line = f"[{role}] {task}"
+        if status:
+            line += f" ({status})"
+        if summary and summary != task:
+            line += f": {summary[:200]}"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def _trim_to_budget(cards: list[ContextCard], budget: int) -> list[ContextCard]:
+    """Trim cards to fit within a character budget. EM trimmed first."""
+    total = sum(len(c.content) for c in cards)
+    if total <= budget:
+        return cards
+
+    # Trim EM first, then RM
+    result = list(cards)
+    for kind in (MemoryKind.EM, MemoryKind.RM, MemoryKind.SM):
+        if total <= budget:
+            break
+        for i, card in enumerate(result):
+            if card.kind == kind and total > budget:
+                excess = total - budget
+                if excess >= len(card.content):
+                    total -= len(card.content)
+                    result[i] = ContextCard(kind=card.kind, content="", source=card.source)
+                else:
+                    result[i] = ContextCard(
+                        kind=card.kind,
+                        content=card.content[: len(card.content) - excess],
+                        source=card.source,
+                    )
+                    total = budget
+
+    return [c for c in result if c.content]
+
+
+def _deduplicate(entries: list[dict]) -> list[dict]:
+    """Deduplicate entries by content, keeping first occurrence."""
+    seen: set[str] = set()
+    result = []
+    for e in entries:
+        content = e.get("content", "")
+        if content not in seen:
+            seen.add(content)
+            result.append(e)
+    return result
+
+
+def _make_id(prefix: str) -> str:
+    """Generate a short unique ID with prefix."""
+    return f"{prefix}_{uuid.uuid4().hex[:8]}"
+
+
+def _now_iso() -> str:
+    """Return current UTC time as ISO 8601 string."""
+    return datetime.now(timezone.utc).isoformat()

dial_memory/scorer.py

@@ -0,0 +1,47 @@
+"""RM keyword relevance scoring — simple keyword overlap, no embeddings."""
+
+from __future__ import annotations
+
+import re
+
+# Common English stop words to ignore during tokenization.
+_STOP_WORDS = frozenset(
+    "a an and are as at be by for from has have in is it of on or that the "
+    "this to was were will with".split()
+)
+
+_TOKEN_RE = re.compile(r"[a-z0-9_]+")
+
+
+def tokenize(text: str) -> set[str]:
+    """Split text into lowercase tokens, stripping stop words."""
+    tokens = set(_TOKEN_RE.findall(text.lower()))
+    return tokens - _STOP_WORDS
+
+
+def score_entry(entry: dict, task_text: str) -> float:
+    """Score a knowledge entry against task text using keyword overlap.
+
+    Returns a float between 0.0 and 1.0.  Higher means more relevant.
+    """
+    entry_keywords = entry.get("keywords", [])
+    if not entry_keywords:
+        return 0.0
+
+    task_tokens = tokenize(task_text)
+    kw_set = {kw.lower() for kw in entry_keywords}
+    overlap = task_tokens & kw_set
+    return len(overlap) / len(kw_set)
+
+
+def score_and_filter(
+    entries: list[dict], task_text: str, min_score: float = 0.3
+) -> list[dict]:
+    """Score entries and return those above *min_score*, sorted descending."""
+    scored = []
+    for entry in entries:
+        s = score_entry(entry, task_text)
+        if s >= min_score:
+            scored.append((s, entry))
+    scored.sort(key=lambda t: t[0], reverse=True)
+    return [entry for _, entry in scored]

dial_memory/storage.py

@@ -0,0 +1,69 @@
+"""File I/O helpers for dial — JSONL read/write, directory setup."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+def ensure_dir(path: Path) -> None:
+    """Create directory (and parents) if it doesn't exist."""
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def append_jsonl(path: Path, record: dict) -> None:
+    """Append a single JSON record to a JSONL file."""
+    ensure_dir(path.parent)
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def read_jsonl(path: Path) -> list[dict]:
+    """Read all records from a JSONL file. Returns [] if file doesn't exist."""
+    if not path.is_file():
+        return []
+    records = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                records.append(json.loads(line))
+    return records
+
+
+def read_jsonl_tail(path: Path, count: int) -> list[dict]:
+    """Read the last *count* records from a JSONL file."""
+    if not path.is_file():
+        return []
+    lines: list[str] = []
+    with open(path, encoding="utf-8") as f:
+        for raw in f:
+            stripped = raw.strip()
+            if stripped:
+                lines.append(stripped)
+    tail = lines[-count:] if count else lines
+    return [json.loads(line) for line in tail]
+
+
+def expand_path(path_str: str) -> Path:
+    """Expand ~ and env vars in a path string."""
+    return Path(os.path.expandvars(os.path.expanduser(path_str)))
+
+
+# -- Path builders -----------------------------------------------------------
+
+
+def em_path(storage_dir: Path, session_id: str) -> Path:
+    """Path to the EM event log for a session."""
+    return storage_dir / "em" / f"{session_id}.jsonl"
+
+
+def knowledge_path(storage_dir: Path) -> Path:
+    """Path to the knowledge JSONL at a given scope root."""
+    return storage_dir / "knowledge" / "knowledge.jsonl"
+
+
+def role_knowledge_path(storage_dir: Path, role: str) -> Path:
+    """Path to role-scoped knowledge JSONL."""
+    return storage_dir / "knowledge" / "roles" / role / "knowledge.jsonl"

dial_memory-0.1.1.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: dial-memory
+Version: 0.1.1
+Summary: Default file-based memory provider for StrawPot
+Project-URL: Homepage, https://github.com/strawpot/dial
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Dial
+
+Default file-based memory provider for [StrawPot](https://github.com/strawpot/strawpot).
+
+Two memory layers — **Event Memory** and a unified **Knowledge store** —
+using local JSON/JSONL files. Zero external dependencies.
+
+## Quick Start
+
+```toml
+# strawpot.toml
+memory = "dial"
+```
+
+## How It Works
+
+- **EM** — Append-only event log per session. Fully automatic, no agent cooperation needed.
+- **Knowledge (SM)** — Facts and conventions, always included. Scoped to global, project, or role.
+- **Knowledge (RM)** — Domain-specific entries, included only when the task keywords match.
+
+Knowledge is scoped at three levels:
+
+| Scope | Example |
+|-------|---------|
+| **Global** | "Always use conventional commits" |
+| **Project** | "This project uses pytest" |
+| **Role** | "Check migration dir before modifying models" |
+
+Agents write knowledge via the denden `remember` RPC during execution:
+
+```bash
+denden send '{"remember": {"content": "This project uses pytest", "scope": "project"}}'
+denden send '{"remember": {"content": "Payments API needs idempotency keys", "keywords": ["payment", "stripe"]}}'
+```
+
+Entries are deduplicated and written directly to the knowledge store.
+
+See [DESIGN.md](DESIGN.md) for architecture details.
+
+## License
+
+[MIT](LICENSE)

dial_memory-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+dial_memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dial_memory/provider.py,sha256=oy9AWvW-ZFJfHadVQhkvxId0kZY-PADXOmnoHrv9AHI,8702
+dial_memory/scorer.py,sha256=B7krPo56LJ8iWPUwiP_GoSyfGFpw2hd6MqZjvIHIrRE,1445
+dial_memory/storage.py,sha256=8cVmowPWFjulQaBFeY4hKrp6arMSs_OjUjG6O6rULbU,2126
+dial_memory-0.1.1.dist-info/METADATA,sha256=gC56tz4DaH1aQKSI4C6GA4Yq_wUnFvaCsGWXZTU_UMw,1661
+dial_memory-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+dial_memory-0.1.1.dist-info/licenses/LICENSE,sha256=3kmwvBd_YyLUyC9H-DI797wdrZDvqH1u0pEEKP5nmJ8,1065
+dial_memory-0.1.1.dist-info/RECORD,,

dial_memory-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dial_memory-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 strawpot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.