qwen-sci 0.2.2__py3-none-any.whl

src/harness/src/openharness/memory/memdir.py

@@ -0,0 +1,52 @@
+"""Memory prompt helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from openharness.memory.paths import get_memory_entrypoint, get_project_memory_dir
+from openharness.memory.schema import (
+    MAX_ENTRYPOINT_BYTES,
+    MEMORY_POLICY_LINES,
+    truncate_entrypoint_content,
+)
+
+
+def load_memory_prompt(
+    cwd: str | Path,
+    *,
+    max_entrypoint_lines: int = 200,
+    max_entrypoint_bytes: int = MAX_ENTRYPOINT_BYTES,
+) -> str | None:
+    """Return the memory prompt section for the current project."""
+    memory_dir = get_project_memory_dir(cwd)
+    entrypoint = get_memory_entrypoint(cwd)
+    lines = [
+        "# Memory",
+        f"- Persistent memory directory: {memory_dir}",
+        "- Use this directory to store durable project and repository context that should survive future sessions.",
+        "- Prefer concise topic files plus an index entry in MEMORY.md.",
+        "",
+        *MEMORY_POLICY_LINES,
+    ]
+
+    if entrypoint.exists():
+        raw = entrypoint.read_text(encoding="utf-8", errors="replace")
+        view = truncate_entrypoint_content(
+            raw,
+            max_lines=max_entrypoint_lines,
+            max_bytes=max_entrypoint_bytes,
+        )
+        content = view.content.strip()
+        if content:
+            lines.extend(["", "## MEMORY.md", "```md", content, "```"])
+    else:
+        lines.extend(
+            [
+                "",
+                "## MEMORY.md",
+                "(not created yet)",
+            ]
+        )
+
+    return "\n".join(lines)

src/harness/src/openharness/memory/migrate.py

@@ -0,0 +1,137 @@
+"""Migration utilities for schema-v1 memory frontmatter."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from openharness.memory.paths import get_project_memory_dir
+from openharness.memory.schema import (
+    memory_metadata_from_path,
+    render_memory_file,
+    split_memory_file,
+    utc_now,
+)
+from openharness.utils.fs import atomic_write_text
+
+
+@dataclass(frozen=True)
+class MigrationSummary:
+    """Summary returned by a memory schema migration run."""
+
+    scanned: int
+    changed: int
+    unchanged: int
+    failed: int
+    dry_run: bool
+    backup_dir: str
+    changed_files: tuple[str, ...]
+    failed_files: tuple[str, ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def migrate_memory(
+    cwd: str | Path,
+    *,
+    memory_dir: str | Path | None = None,
+    default_type: str = "project",
+    default_category: str = "knowledge",
+    apply: bool = False,
+) -> MigrationSummary:
+    """Backfill schema-v1 frontmatter for top-level memory markdown files."""
+
+    root = Path(memory_dir).expanduser().resolve() if memory_dir is not None else get_project_memory_dir(cwd)
+    root.mkdir(parents=True, exist_ok=True)
+    files = sorted(path for path in root.glob("*.md") if path.name != "MEMORY.md")
+    changed_payloads: list[tuple[Path, str]] = []
+    failed_files: list[str] = []
+    seen_ids: set[str] = set()
+    now = utc_now()
+
+    for path in files:
+        try:
+            content = path.read_text(encoding="utf-8")
+            metadata, body, _, _ = split_memory_file(content)
+            migrated = memory_metadata_from_path(
+                path,
+                metadata,
+                body,
+                now=now,
+                source="migration",
+                default_type=default_type,
+                default_category=default_category,
+                seen_ids=seen_ids,
+            )
+            rendered = render_memory_file(migrated, body)
+            if rendered != content:
+                changed_payloads.append((path, rendered))
+        except OSError:
+            failed_files.append(path.name)
+
+    backup_dir = ""
+    if apply and changed_payloads:
+        backup_path = _create_migration_backup(root)
+        backup_dir = str(backup_path)
+        for path, rendered in changed_payloads:
+            atomic_write_text(path, rendered)
+
+    changed_files = tuple(path.name for path, _ in changed_payloads)
+    return MigrationSummary(
+        scanned=len(files),
+        changed=len(changed_payloads),
+        unchanged=len(files) - len(changed_payloads) - len(failed_files),
+        failed=len(failed_files),
+        dry_run=not apply,
+        backup_dir=backup_dir,
+        changed_files=changed_files,
+        failed_files=tuple(failed_files),
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Command-line entrypoint for one-off memory migrations."""
+
+    parser = argparse.ArgumentParser(description="Backfill OpenHarness memory schema metadata.")
+    parser.add_argument("--cwd", default=".", help="Project cwd whose memory store should be migrated.")
+    parser.add_argument("--memory-dir", default=None, help="Explicit memory directory to migrate.")
+    parser.add_argument("--default-type", default="project", help="Type for legacy files without one.")
+    parser.add_argument("--default-category", default="knowledge", help="Category for legacy files without one.")
+    parser.add_argument("--dry-run", action="store_true", help="Report files that would change.")
+    parser.add_argument("--apply", action="store_true", help="Write migrated files and create a backup.")
+    args = parser.parse_args(argv)
+    if args.dry_run == args.apply:
+        parser.error("pass exactly one of --dry-run or --apply")
+    summary = migrate_memory(
+        args.cwd,
+        memory_dir=args.memory_dir,
+        default_type=args.default_type,
+        default_category=args.default_category,
+        apply=args.apply,
+    )
+    print(json.dumps(summary.as_dict(), indent=2, ensure_ascii=False))
+    return 0
+
+
+def _create_migration_backup(memory_dir: Path) -> Path:
+    timestamp = utc_now().strftime("%Y%m%d-%H%M%S")
+    backup_dir = memory_dir / "backups" / f"migration-{timestamp}"
+    suffix = 2
+    while backup_dir.exists():
+        backup_dir = memory_dir / "backups" / f"migration-{timestamp}-{suffix}"
+        suffix += 1
+    backup_dir.mkdir(parents=True, exist_ok=False)
+    for path in sorted(memory_dir.glob("*.md")):
+        shutil.copy2(path, backup_dir / path.name)
+    usage_index = memory_dir / "usage_index.json"
+    if usage_index.exists():
+        shutil.copy2(usage_index, backup_dir / usage_index.name)
+    return backup_dir
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/harness/src/openharness/memory/paths.py

@@ -0,0 +1,22 @@
+"""Paths for persistent project memory."""
+
+from __future__ import annotations
+
+from hashlib import sha1
+from pathlib import Path
+
+from openharness.config.paths import get_data_dir
+
+
+def get_project_memory_dir(cwd: str | Path) -> Path:
+    """Return the persistent memory directory for a project."""
+    path = Path(cwd).resolve()
+    digest = sha1(str(path).encode("utf-8")).hexdigest()[:12]
+    memory_dir = get_data_dir() / "memory" / f"{path.name}-{digest}"
+    memory_dir.mkdir(parents=True, exist_ok=True)
+    return memory_dir
+
+
+def get_memory_entrypoint(cwd: str | Path) -> Path:
+    """Return the project memory entrypoint file."""
+    return get_project_memory_dir(cwd) / "MEMORY.md"

src/harness/src/openharness/memory/relevance.py

@@ -0,0 +1,145 @@
+"""Relevant memory selection and formatting."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable
+
+from openharness.memory.scan import scan_memory_files
+from openharness.memory.schema import memory_age_label, memory_freshness_text
+from openharness.memory.search import find_relevant_memories
+from openharness.memory.types import MemoryHeader
+
+
+@dataclass(frozen=True)
+class RelevantMemory:
+    """A memory selected for prompt injection."""
+
+    header: MemoryHeader
+    freshness: str = ""
+
+
+MemorySelector = Callable[[str, list[MemoryHeader]], list[str]]
+
+
+def build_memory_manifest(headers: Iterable[MemoryHeader]) -> str:
+    """Render a compact manifest for selector prompts and diagnostics."""
+
+    lines: list[str] = []
+    for header in headers:
+        prefix = f"[{header.memory_type or 'memory'}]"
+        bits = [
+            prefix,
+            header.relative_path or header.path.name,
+            f"({memory_age_label(header.modified_at)})",
+        ]
+        if header.description:
+            bits.append(f"- {header.description}")
+        lines.append(" ".join(bits))
+    return "\n".join(lines)
+
+
+def select_relevant_memories(
+    query: str,
+    cwd: str | Path,
+    *,
+    max_results: int = 5,
+    already_surfaced: set[str] | None = None,
+    selector: MemorySelector | None = None,
+) -> list[RelevantMemory]:
+    """Return relevant memories with duplicate and freshness handling.
+
+    ``selector`` is an optional side-query style reranker. It receives the query
+    and a heuristic shortlist, and returns relative paths in desired order.
+    """
+
+    surfaced = already_surfaced or set()
+    heuristic = [
+        header
+        for header in find_relevant_memories(query, cwd, max_results=max(10, max_results * 3))
+        if (header.relative_path or str(header.path)) not in surfaced
+    ]
+    selected = _apply_selector(query, heuristic, selector=selector, max_results=max_results)
+    result: list[RelevantMemory] = []
+    for header in selected[:max_results]:
+        result.append(RelevantMemory(header=header, freshness=memory_freshness_text(header.modified_at)))
+    return result
+
+
+def select_manifest_memories(
+    query: str,
+    cwd: str | Path,
+    *,
+    max_results: int = 5,
+    selector: MemorySelector | None = None,
+) -> list[RelevantMemory]:
+    """Select from the full manifest instead of heuristic matches only."""
+
+    headers = scan_memory_files(cwd, max_files=200)
+    selected = _apply_selector(query, headers, selector=selector, max_results=max_results)
+    return [
+        RelevantMemory(header=header, freshness=memory_freshness_text(header.modified_at))
+        for header in selected[:max_results]
+    ]
+
+
+def format_relevant_memories(memories: Iterable[RelevantMemory], *, max_chars: int = 8000) -> str:
+    """Render selected memories for prompt context."""
+
+    lines = ["# Relevant Memories"]
+    for item in memories:
+        header = item.header
+        content = header.path.read_text(encoding="utf-8", errors="replace").strip()
+        if item.freshness:
+            lines.extend(["", f"## {header.relative_path or header.path.name}", f"> {item.freshness}"])
+        else:
+            lines.extend(["", f"## {header.relative_path or header.path.name}"])
+        lines.extend(["```md", content[:max_chars], "```"])
+    return "\n".join(lines)
+
+
+def json_selector_from_text(text: str) -> list[str]:
+    """Parse a selector response as either JSON list or newline paths."""
+
+    stripped = text.strip()
+    if not stripped:
+        return []
+    try:
+        payload = json.loads(stripped)
+    except json.JSONDecodeError:
+        return [line.strip("- ").strip() for line in stripped.splitlines() if line.strip()]
+    if isinstance(payload, list):
+        return [str(item).strip() for item in payload if str(item).strip()]
+    if isinstance(payload, dict) and isinstance(payload.get("paths"), list):
+        return [str(item).strip() for item in payload["paths"] if str(item).strip()]
+    return []
+
+
+def _apply_selector(
+    query: str,
+    headers: list[MemoryHeader],
+    *,
+    selector: MemorySelector | None,
+    max_results: int,
+) -> list[MemoryHeader]:
+    if not headers or selector is None:
+        return headers[:max_results]
+    requested = selector(query, headers)
+    by_path = {header.relative_path or header.path.name: header for header in headers}
+    selected: list[MemoryHeader] = []
+    seen: set[str] = set()
+    for path in requested:
+        header = by_path.get(path)
+        if header is None or path in seen:
+            continue
+        selected.append(header)
+        seen.add(path)
+    if len(selected) < max_results:
+        selected.extend(
+            header
+            for header in headers
+            if (header.relative_path or header.path.name) not in seen
+        )
+    return selected[:max_results]

src/harness/src/openharness/memory/scan.py

@@ -0,0 +1,116 @@
+"""Scan project memory files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from openharness.memory.paths import get_project_memory_dir
+from openharness.memory.schema import (
+    coerce_bool,
+    coerce_int,
+    coerce_optional_int,
+    coerce_str_list,
+    first_content_line,
+    is_memory_expired,
+    split_memory_file,
+)
+from openharness.memory.types import MemoryHeader
+
+
+def scan_memory_files(
+    cwd: str | Path,
+    *,
+    max_files: int | None = 50,
+    include_disabled: bool = False,
+    include_expired: bool = False,
+    memory_dir: str | Path | None = None,
+) -> list[MemoryHeader]:
+    """Return memory headers sorted by newest first."""
+    memory_dir = Path(memory_dir) if memory_dir is not None else get_project_memory_dir(cwd)
+    headers: list[MemoryHeader] = []
+    for path in memory_dir.glob("*.md"):
+        if path.name == "MEMORY.md":
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        header = _parse_memory_file(path, text)
+        if header.disabled and not include_disabled:
+            continue
+        if is_memory_expired(_metadata_from_header(header)) and not include_expired:
+            continue
+        headers.append(header)
+    headers.sort(key=lambda item: item.modified_at, reverse=True)
+    if max_files is None:
+        return headers
+    return headers[:max_files]
+
+
+def _parse_memory_file(path: Path, content: str) -> MemoryHeader:
+    """Parse a memory file, extracting YAML frontmatter when present."""
+    metadata, body, _, _ = split_memory_file(content)
+    lines = body.splitlines()
+    title = path.stem
+    description = ""
+    memory_type = ""
+    if metadata.get("name"):
+        title = str(metadata["name"])
+    if metadata.get("description"):
+        description = str(metadata["description"])
+    if metadata.get("type"):
+        memory_type = str(metadata["type"])
+
+    # Fallback: first non-empty, non-frontmatter line as description
+    desc_line_idx: int | None = None
+    if not description:
+        fallback = first_content_line("\n".join(lines[:10]))
+        if fallback:
+            description = fallback
+        for idx, line in enumerate(lines[:10]):
+            stripped = line.strip()
+            if stripped[:200] == description:
+                desc_line_idx = idx
+                break
+
+    # Build body preview from content after frontmatter, excluding the
+    # line already used as description so search scoring stays consistent.
+    body_lines = [
+        line.strip()
+        for idx, line in enumerate(lines)
+        if line.strip()
+        and not line.strip().startswith("#")
+        and idx != desc_line_idx
+    ]
+    body_preview = " ".join(body_lines)[:300]
+
+    return MemoryHeader(
+        path=path,
+        title=title,
+        description=description,
+        modified_at=path.stat().st_mtime,
+        memory_type=memory_type,
+        body_preview=body_preview,
+        id=str(metadata.get("id") or ""),
+        schema_version=coerce_int(metadata.get("schema_version"), default=0),
+        category=str(metadata.get("category") or ""),
+        importance=coerce_int(metadata.get("importance"), default=0),
+        source=str(metadata.get("source") or ""),
+        signature=str(metadata.get("signature") or ""),
+        created_at=str(metadata.get("created_at") or ""),
+        updated_at=str(metadata.get("updated_at") or ""),
+        ttl_days=coerce_optional_int(metadata.get("ttl_days")),
+        disabled=coerce_bool(metadata.get("disabled"), default=False),
+        supersedes=coerce_str_list(metadata.get("supersedes")),
+        relative_path=path.name,
+        tags=coerce_str_list(metadata.get("tags")),
+        frontmatter=metadata,
+    )
+
+
+def _metadata_from_header(header: MemoryHeader) -> dict[str, object]:
+    return {
+        "created_at": header.created_at,
+        "updated_at": header.updated_at,
+        "ttl_days": header.ttl_days,
+    }