rfnry-memory 0.1.0__tar.gz

rfnry_memory-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+dist/
+.env*
+node_modules/
+examples/**/uv.lock
+examples/**/.work/
+docs/plans/
+docs/superpowers/
+.superpowers/
+.worktrees

rfnry_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rfnry (github.com/rfnry)
+
+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.

rfnry_memory-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.5
+Name: rfnry-memory
+Version: 0.1.0
+Summary: Hybrid-retrieval memory system for AI agents
+Project-URL: Repository, https://github.com/rfnry/memory
+Project-URL: Documentation, https://github.com/rfnry/memory/blob/main/docs/memory.md
+Project-URL: Issues, https://github.com/rfnry/memory/issues
+Author-email: rfnry <contact@rfnry.dev>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.13.4
+Provides-Extra: dev
+Requires-Dist: asyncpg<1.0,>=0.31.0; extra == 'dev'
+Requires-Dist: mypy>=2.3.1; extra == 'dev'
+Requires-Dist: poethepoet>=0.48.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.16.4; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: asyncpg<1.0,>=0.31.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# rfnry-memory
+
+Hybrid-retrieval memory system for AI agents.
+
+[`docs/memory.md`](https://github.com/rfnry/memory/blob/main/docs/memory.md).
+[`docs/api.md`](https://github.com/rfnry/memory/blob/main/docs/api.md).

rfnry_memory-0.1.0/README.md

@@ -0,0 +1,6 @@
+# rfnry-memory
+
+Hybrid-retrieval memory system for AI agents.
+
+[`docs/memory.md`](https://github.com/rfnry/memory/blob/main/docs/memory.md).
+[`docs/api.md`](https://github.com/rfnry/memory/blob/main/docs/api.md).

rfnry_memory-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "rfnry-memory"
+version = "0.1.0"
+description = "Hybrid-retrieval memory system for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{name = "rfnry", email = "contact@rfnry.dev"}]
+dependencies = [
+    "pydantic>=2.13.4",
+]
+
+[project.urls]
+Repository = "https://github.com/rfnry/memory"
+Documentation = "https://github.com/rfnry/memory/blob/main/docs/memory.md"
+Issues = "https://github.com/rfnry/memory/issues"
+
+[project.scripts]
+rfnry-memory = "rfnry_memory.cli:main"
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.31.0,<1.0"]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.4",
+    "mypy>=2.3.1",
+    "poethepoet>=0.48.0",
+    "asyncpg>=0.31.0,<1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rfnry_memory"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+markers = [
+    "live: calls real models (set RFNRY_LIVE_ADAPTERS to a module path)",
+]
+addopts = "-m 'not live'"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "UP", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "rfnry_memory.ranking.BM25",
+    "rfnry_memory.ranking.bm25.BM25",
+    "rfnry_memory.fusion.RRF",
+    "rfnry_memory.fusion.rrf.RRF",
+]
+
+[tool.poe.tasks]
+format = { cmd = "ruff format src tests" }
+check = { cmd = "ruff check src tests" }
+"check:fix" = { cmd = "ruff check --fix src tests" }
+typecheck = { cmd = "mypy" }
+test = { cmd = "pytest -q" }
+"test:integration" = { cmd = "pytest -q tests/integration" }
+"test:e2e" = { cmd = "pytest -q -m live" }
+
+[tool.mypy]
+strict = true
+files = ["src/rfnry_memory", "tests"]
+
+[[tool.mypy.overrides]]
+module = ["asyncpg.*"]
+ignore_missing_imports = true

rfnry_memory-0.1.0/src/rfnry_memory/__init__.py

@@ -0,0 +1,153 @@
+from rfnry_memory.errors import (
+    ConfigurationError,
+    InputError,
+    MemoryException,
+    ModelError,
+    NotFoundError,
+    StorageError,
+)
+from rfnry_memory.fusion import RRF, Fusion, RelativeScore
+from rfnry_memory.index import HNSW, IVFFlat, VectorIndex
+from rfnry_memory.memory import Memory
+from rfnry_memory.models import (
+    Answer,
+    AnswerLike,
+    Audio,
+    Check,
+    CheckAnswer,
+    Choice,
+    ChoiceAnswer,
+    Chunk,
+    Chunking,
+    Content,
+    CorpusDescription,
+    CorpusFingerprint,
+    Counts,
+    Decided,
+    DecidedLike,
+    DecisionModel,
+    Document,
+    DocumentEmbeddingModel,
+    EmbeddingModel,
+    Entity,
+    EntityIn,
+    GenerationModel,
+    Hit,
+    Hits,
+    Image,
+    Ingested,
+    Judgement,
+    JudgementName,
+    Kind,
+    Language,
+    Match,
+    Message,
+    Neighborhood,
+    Part,
+    PillarReport,
+    Question,
+    QuestionLike,
+    Ref,
+    Relation,
+    RelationIn,
+    Remembered,
+    Reply,
+    ReplyLike,
+    Score,
+    ScoreAnswer,
+    Section,
+    Source,
+    SourceIn,
+    State,
+    Story,
+    Synced,
+    Text,
+    ToolCall,
+    ToolSpec,
+    Usage,
+    confidence,
+)
+from rfnry_memory.postgres import PostgresStorage
+from rfnry_memory.ranking import BM25, CoverDensity, TextRanking
+from rfnry_memory.tools import MemoryTools, Tool, Tools
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Answer",
+    "AnswerLike",
+    "Check",
+    "CheckAnswer",
+    "Choice",
+    "ChoiceAnswer",
+    "Chunk",
+    "Chunking",
+    "ConfigurationError",
+    "CorpusDescription",
+    "CorpusFingerprint",
+    "Counts",
+    "Decided",
+    "DecidedLike",
+    "DecisionModel",
+    "DocumentEmbeddingModel",
+    "EmbeddingModel",
+    "Entity",
+    "EntityIn",
+    "GenerationModel",
+    "HNSW",
+    "BM25",
+    "CoverDensity",
+    "TextRanking",
+    "RRF",
+    "RelativeScore",
+    "Fusion",
+    "Hit",
+    "Hits",
+    "IVFFlat",
+    "Ingested",
+    "InputError",
+    "Judgement",
+    "JudgementName",
+    "Kind",
+    "Match",
+    "Language",
+    "Memory",
+    "MemoryException",
+    "MemoryTools",
+    "Message",
+    "ModelError",
+    "Neighborhood",
+    "NotFoundError",
+    "PillarReport",
+    "PostgresStorage",
+    "Question",
+    "QuestionLike",
+    "Ref",
+    "Relation",
+    "RelationIn",
+    "Remembered",
+    "Reply",
+    "ReplyLike",
+    "Score",
+    "ScoreAnswer",
+    "Section",
+    "Source",
+    "SourceIn",
+    "State",
+    "StorageError",
+    "Story",
+    "Synced",
+    "Tool",
+    "ToolCall",
+    "ToolSpec",
+    "Tools",
+    "Usage",
+    "VectorIndex",
+    "confidence",
+    "Text",
+    "Image",
+    "Audio",
+    "Document",
+    "Part",
+    "Content",
+]

rfnry_memory-0.1.0/src/rfnry_memory/chunking/chunker.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from rfnry_memory.chunking.splitter import RecursiveTextSplitter
+from rfnry_memory.chunking.structure import (
+    build_heading_spans,
+    find_atomic_regions,
+    section_path_at,
+)
+
+
+class Piece(BaseModel):
+    title: str | None
+    text: str
+
+
+def chunk_text(text: str, *, chunk_chars: int, overlap_chars: int) -> list[Piece]:
+    text = text.strip()
+    if not text:
+        return []
+    regions = find_atomic_regions(text)
+    spans = build_heading_spans(text, regions)
+    splitter = RecursiveTextSplitter(chunk_size=chunk_chars, chunk_overlap=overlap_chars)
+    pieces: list[Piece] = []
+
+    def free(start: int, end: int) -> None:
+        for piece, offset in splitter.split_text_with_offsets(text[start:end]):
+            pieces.append(Piece(title=section_path_at(start + offset, spans), text=piece))
+
+    cursor = 0
+    for region in regions:
+        free(cursor, region.start)
+        pieces.append(
+            Piece(title=section_path_at(region.start, spans), text=region.content.strip())
+        )
+        cursor = region.end
+    free(cursor, len(text))
+    return [piece for piece in pieces if piece.text]

rfnry_memory-0.1.0/src/rfnry_memory/chunking/splitter.py

@@ -0,0 +1,93 @@
+import re
+
+SEPARATORS = ["\n\n", "\n", ". ", " ", ""]
+
+
+def _split(text: str, separator: str) -> list[tuple[int, int]]:
+    if not separator:
+        return [(i, i + 1) for i in range(len(text))]
+    spans: list[tuple[int, int]] = []
+    prev = 0
+    for m in re.finditer(re.escape(separator), text):
+        spans.append((prev, m.start()))
+        prev = m.end()
+    spans.append((prev, len(text)))
+    return [(s, e) for s, e in spans if e > s]
+
+
+class RecursiveTextSplitter:
+    def __init__(self, chunk_size: int, chunk_overlap: int) -> None:
+        self._chunk_size = chunk_size
+        self._chunk_overlap = chunk_overlap
+
+    def split_text_with_offsets(self, text: str) -> list[tuple[str, int]]:
+        return self._split(text, SEPARATORS, 0)
+
+    def _emit(self, text: str, start: int, end: int, base: int) -> list[tuple[str, int]]:
+        chunk = text[start:end]
+        s = start + len(chunk) - len(chunk.lstrip())
+        e = end - (len(chunk) - len(chunk.rstrip()))
+        if e <= s:
+            return []
+        return [(text[s:e], base + s)]
+
+    def _merge(self, spans: list[tuple[int, int]], separator: str) -> list[tuple[int, int]]:
+        joiner = len(separator)
+        chunks: list[tuple[int, int]] = []
+        current: list[tuple[int, int]] = []
+        total = 0
+        for span in spans:
+            size = span[1] - span[0]
+            if total + size + (joiner if current else 0) > self._chunk_size and current:
+                chunks.append((current[0][0], current[-1][1]))
+                while total > self._chunk_overlap or (
+                    total + size + (joiner if current else 0) > self._chunk_size and total > 0
+                ):
+                    total -= current[0][1] - current[0][0] + (joiner if len(current) > 1 else 0)
+                    current = current[1:]
+            current.append(span)
+            total += size + (joiner if len(current) > 1 else 0)
+        if current:
+            chunks.append((current[0][0], current[-1][1]))
+        return chunks
+
+    def _split(self, text: str, separators: list[str], base: int) -> list[tuple[str, int]]:
+        if not text:
+            return []
+        if len(text) <= self._chunk_size:
+            return self._emit(text, 0, len(text), base)
+        separator = separators[-1]
+        remaining: list[str] = []
+        for i, sep in enumerate(separators):
+            if not sep:
+                separator = sep
+                break
+            if sep in text:
+                separator = sep
+                remaining = separators[i + 1 :]
+                break
+        found: list[tuple[str, int]] = []
+        good: list[tuple[int, int]] = []
+        for span in _split(text, separator):
+            piece = text[span[0] : span[1]]
+            if len(piece) < self._chunk_size:
+                good.append(span)
+                continue
+            for s, e in self._merge(good, separator):
+                found.extend(self._emit(text, s, e, base))
+            good = []
+            if remaining:
+                found.extend(self._split(piece, remaining, base + span[0]))
+            elif len(piece) > self._chunk_size:
+                step = max(1, self._chunk_size - self._chunk_overlap)
+                for start in range(0, len(piece), step):
+                    found.extend(
+                        self._emit(
+                            piece, start, min(start + self._chunk_size, len(piece)), base + span[0]
+                        )
+                    )
+            else:
+                found.extend(self._emit(text, span[0], span[1], base))
+        for s, e in self._merge(good, separator):
+            found.extend(self._emit(text, s, e, base))
+        return found

rfnry_memory-0.1.0/src/rfnry_memory/chunking/structure.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_FENCE_OPEN_RE = re.compile(r"```[a-zA-Z0-9_+-]*")
+_TABLE_RE = re.compile(
+    r"(?:^\|[^\n]+\|\n)"
+    r"(?:^\|[\s\-:|]+\|\n)"
+    r"(?:^\|[^\n]+\|\n?)+",
+    re.MULTILINE,
+)
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)$", re.MULTILINE)
+
+
+@dataclass
+class AtomicRegion:
+    start: int
+    end: int
+    content: str
+
+
+@dataclass
+class HeadingSpan:
+    start: int
+    end: int
+    path: tuple[str, ...]
+
+
+def _iter_code_fences(text: str) -> list[AtomicRegion]:
+    lines = text.splitlines(keepends=True)
+    starts: list[int] = []
+    pos = 0
+    for line in lines:
+        starts.append(pos)
+        pos += len(line)
+
+    regions: list[AtomicRegion] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        if _FENCE_OPEN_RE.fullmatch(lines[i].rstrip("\r\n")):
+            j = i + 1
+            while j < n and not lines[j].startswith("```"):
+                j += 1
+            if j < n:
+                start = starts[i]
+                end = starts[j] + 3
+                regions.append(AtomicRegion(start, end, text[start:end]))
+                i = j + 1
+                continue
+        i += 1
+    return regions
+
+
+def find_atomic_regions(text: str) -> list[AtomicRegion]:
+    regions: list[AtomicRegion] = []
+    regions.extend(_iter_code_fences(text))
+    for m in _TABLE_RE.finditer(text):
+        regions.append(AtomicRegion(m.start(), m.end(), m.group(0)))
+    regions.sort(key=lambda r: (r.start, -r.end))
+    merged: list[AtomicRegion] = []
+    for region in regions:
+        if merged and region.end <= merged[-1].end:
+            continue
+        if merged and region.start < merged[-1].end:
+            prev = merged[-1]
+            merged[-1] = AtomicRegion(prev.start, region.end, text[prev.start : region.end])
+            continue
+        merged.append(region)
+    return merged
+
+
+def build_heading_spans(
+    text: str,
+    exclude_regions: list[AtomicRegion] | None = None,
+) -> list[HeadingSpan]:
+    headings: list[tuple[int, int, str]] = []
+    exclude = exclude_regions or []
+    for m in _HEADING_RE.finditer(text):
+        offset = m.start()
+        if any(r.start <= offset < r.end for r in exclude):
+            continue
+        title = m.group(2).strip()
+        title = title.rstrip("#").rstrip() or title
+        headings.append((offset, len(m.group(1)), title))
+    if not headings:
+        return []
+    spans: list[HeadingSpan] = []
+    stack: list[tuple[int, str]] = []
+    for i, (offset, level, title) in enumerate(headings):
+        while stack and stack[-1][0] >= level:
+            stack.pop()
+        stack.append((level, title))
+        end = headings[i + 1][0] if i + 1 < len(headings) else len(text)
+        spans.append(
+            HeadingSpan(
+                start=offset,
+                end=end,
+                path=tuple(t for _, t in stack),
+            )
+        )
+    return spans
+
+
+def section_path_at(offset: int, spans: list[HeadingSpan]) -> str | None:
+    for s in spans:
+        if s.start <= offset < s.end:
+            return " > ".join(s.path)
+    return None