AbstractMemory 0.2.3__tar.gz → 0.2.5__tar.gz

abstractmemory-0.2.5/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,73 @@
+name: Bug report
+description: Report a reproducible AbstractMemory bug
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Include enough detail to reproduce the store, query, embedding, or packaging behavior.
+  - type: input
+    id: version
+    attributes:
+      label: AbstractMemory version
+      description: Output of `python -c "from importlib.metadata import version; print(version('AbstractMemory'))"`
+      placeholder: "0.2.5"
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Store or area
+      options:
+        - in-memory store
+        - sqlite store
+        - lancedb store
+        - embeddings
+        - query/model contract
+        - packaging/install
+        - documentation
+        - other
+    validations:
+      required: true
+  - type: textarea
+    id: observed
+    attributes:
+      label: What happened?
+      description: Describe the incorrect behavior, including exact errors or unexpected query results.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction steps
+      description: Include commands, Python snippets, store backend, query inputs, and installed extras.
+      placeholder: |
+        1. Create a SQLiteTripleStore with ...
+        2. Add assertions ...
+        3. Query with ...
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, installed extras, backend, and relevant package versions.
+      placeholder: |
+        macOS 15, Python 3.12
+        pip install "AbstractMemory[all-apple]"
+    validations:
+      required: true
+  - type: textarea
+    id: artifacts
+    attributes:
+      label: Logs or artifacts
+      description: Attach logs, store schema details, query payloads, or related files.
+    validations:
+      required: false

abstractmemory-0.2.5/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e ".[test]"
+      - name: Pytest
+        run: python -m pytest -q -m "not integration"
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Build
+        run: |
+          python -m pip install -U pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*

abstractmemory-0.2.5/.github/workflows/release.yml

@@ -0,0 +1,179 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version, with or without the leading v (example: 0.2.5)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e ".[test]"
+      - name: Pytest
+        run: python -m pytest -q -m "not integration"
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: [test]
+    outputs:
+      version: ${{ steps.release-meta.outputs.version }}
+      tag: ${{ steps.release-meta.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install build tools
+        run: |
+          python -m pip install -U pip
+          python -m pip install build twine
+      - name: Validate tag, version, and changelog
+        id: release-meta
+        env:
+          RELEASE_INPUT_VERSION: ${{ github.event.inputs.version || '' }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          version_input = os.environ.get("RELEASE_INPUT_VERSION", "").strip()
+          ref_name = os.environ["GITHUB_REF_NAME"].strip()
+          raw_version = version_input or ref_name
+          version = raw_version[1:] if raw_version.startswith("v") else raw_version
+          if not re.fullmatch(r"\d+\.\d+\.\d+(?:[a-zA-Z0-9.-]+)?", version):
+              raise SystemExit(f"Invalid release version: {raw_version!r}")
+          tag = f"v{version}"
+
+          project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          package_version = project["version"]
+          if version != package_version:
+              raise SystemExit(
+                  f"Tag version {version!r} does not match package version {package_version!r}"
+              )
+
+          changelog = Path("CHANGELOG.md").read_text(encoding="utf-8")
+          header = re.search(rf"^## \[?{re.escape(version)}\]? - .+$", changelog, re.MULTILINE)
+          if not header:
+              raise SystemExit(f"CHANGELOG.md has no entry for {version}")
+
+          rest = changelog[header.end():]
+          next_header = re.search(r"^## ", rest, re.MULTILINE)
+          notes = rest[: next_header.start() if next_header else len(rest)].strip()
+          if not notes:
+              raise SystemExit(f"CHANGELOG.md entry for {version} is empty")
+
+          Path("release-notes.md").write_text(notes + "\n", encoding="utf-8")
+          github_output = Path(os.environ["GITHUB_OUTPUT"])
+          with github_output.open("a", encoding="utf-8") as fh:
+              print(f"version={version}", file=fh)
+              print(f"tag={tag}", file=fh)
+          PY
+      - name: Build
+        run: python -m build
+      - name: Check distributions
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-notes
+          path: release-notes.md
+
+  ensure-tag:
+    name: Ensure release tag
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Create annotated tag for manual releases
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          tag="${{ needs.build.outputs.tag }}"
+          if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
+            echo "Tag ${tag} already exists on origin."
+            exit 1
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "${tag}" -m "AbstractMemory ${tag}"
+          git push origin "${tag}"
+      - name: Tag already supplied by push trigger
+        if: github.event_name != 'workflow_dispatch'
+        run: echo "Using existing tag ${{ needs.build.outputs.tag }}"
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, ensure-tag]
+    environment:
+      name: pypi
+      url: https://pypi.org/project/abstractmemory/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [build, ensure-tag, publish-pypi]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-notes
+          path: .
+      - uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.build.outputs.tag }}
+          name: AbstractMemory ${{ needs.build.outputs.tag }}
+          body_path: release-notes.md
+          files: dist/*
+          fail_on_unmatched_files: true

abstractmemory-0.2.5/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.DS_Store
+.venv/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+untracked/

abstractmemory-0.2.5/ACKNOWLEDGMENTS.md

@@ -0,0 +1,15 @@
+# Acknowledgments
+
+AbstractMemory builds on a number of great open-source tools and ideas.
+
+## Libraries
+
+- **LanceDB** (`lancedb`) — optional persistent/vector backend used by `LanceDBTripleStore` (see `.[lancedb]` extra in `pyproject.toml`).
+- **pytest** (`pytest`) — development and contract tests (see `.[dev]` extra in `pyproject.toml`).
+- **Hatchling** (`hatchling`) — packaging/build backend (see `[build-system]` in `pyproject.toml`).
+
+## Ecosystem
+
+- The broader **AbstractFramework** project for shaping the boundaries between runtime provenance, model execution, and memory storage.
+
+If we missed a credit, please open a small PR to update this file.

abstractmemory-0.2.5/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) (pre-1.0).
+
+## Unreleased
+
+*No unreleased changes.*
+
+## [0.2.5] - 2026-05-08
+
+### Added
+- Added GitHub Actions CI for Python 3.10 through 3.12 with pytest and package
+  build checks.
+- Added a trusted-publishing release workflow for tagged or manually dispatched
+  releases, including version/changelog validation, distribution artifacts,
+  PyPI publication, and GitHub Release creation.
+- Added an AbstractMemory GitHub bug report template.
+- Added a `test` optional dependency extra for CI and release validation.
+
+## 0.2.4 - 2026-05-08
+
+### Added
+- Added install-profile compatibility extras:
+  `AbstractMemory[apple]`, `AbstractMemory[gpu]`,
+  `AbstractMemory[all-apple]`, and `AbstractMemory[all-gpu]`.
+- Planned backlog overview and standalone items for semantics-aligned memory records, SQLite compatibility/store capabilities, bounded graph traversal, recall traces, lineage, deterministic anchors, and read-only observer contracts.
+
+### Changed
+- `AbstractMemory[all-apple]` and `AbstractMemory[all-gpu]` now install the
+  LanceDB-backed vector-capable store dependency, matching the existing
+  `lancedb`/`all` profile behavior.
+- `AbstractMemory[apple]` and `AbstractMemory[gpu]` remain no-op aliases
+  because Memory itself has no hardware-specific runtime engine.
+- Docs: clarify AbstractFramework ecosystem positioning, update PyPI install wording, and add a gateway-managed embeddings example.
+- Docs: align README/API/store/FAQ/agent context with the exported `SQLiteTripleStore` and clarify semantic-query support by backend.
+- Docs: document current release-channel drift between this source tree, PyPI, and remote tags.
+
+### Fixed
+- Test configuration now declares the local `basic` marker.
+- `LanceDBTripleStore` avoids the deprecated LanceDB `table_names()` API when `list_tables()` is available.
+
+## 0.0.2 - 2026-02-04
+
+### Added
+- User-facing documentation set with getting started, API, stores, architecture diagram, and FAQ.
+- Agent-oriented context files: `llms.txt` and `llms-full.txt`.
+
+### Changed
+- `LanceDBTripleStore` non-semantic queries now apply `order` by `observed_at` before applying `limit` (deterministic behavior aligned with `InMemoryTripleStore`).
+
+### Fixed
+- Ordering/limit interaction for non-semantic queries in `LanceDBTripleStore` (covered by new tests).
+
+## 0.0.1 - 2026-01-12
+
+### Added
+- `TripleAssertion` and `TripleQuery` data models.
+- `InMemoryTripleStore` (dependency-free) and `LanceDBTripleStore` (optional).
+- `AbstractGatewayTextEmbedder` adapter for gateway-managed embeddings.

abstractmemory-0.2.5/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+Thanks for your interest in improving AbstractMemory.
+
+This repository uses a `src/` layout and keeps the public API intentionally small.
+
+AbstractMemory is part of the **AbstractFramework** ecosystem (see [`README.md`](README.md) and [`docs/architecture.md`](docs/architecture.md)).
+
+## Development setup
+
+Requirements:
+- Python 3.10+ (see `pyproject.toml`)
+
+Install (editable):
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Optional (LanceDB backend + tests):
+
+```bash
+python -m pip install -e ".[lancedb]"
+```
+
+More details: [`docs/development.md`](docs/development.md).
+
+## Run tests
+
+```bash
+python -m pytest -q
+```
+
+## What to contribute
+
+Good first contributions:
+- Improve docs (keep statements evidence-based and link to code/tests).
+- Add tests for edge cases and contracts.
+- Make error messages more actionable.
+- Add small, well-scoped features that keep the v0 API minimal.
+
+## Contribution guidelines
+
+- Keep changes focused; avoid drive-by refactors.
+- Add tests for behavior changes (especially store/query semantics).
+- Update docs when you change public behavior:
+  - `README.md` and `docs/getting-started.md` for user-facing usage
+  - `docs/api.md` for public API contracts
+  - `docs/architecture.md` when boundaries/diagrams change
+  - `CHANGELOG.md` for notable changes
+- If you add a new dependency, keep it optional unless strictly required.
+
+## PR checklist
+
+- `python -m pytest -q` passes locally
+- Docs stay evidence-based (link to code/tests for contracts)
+- Public API changes are reflected in `src/abstractmemory/__init__.py` and `docs/api.md`
+
+## Security issues
+
+Please do not open public issues for vulnerabilities. See [`SECURITY.md`](SECURITY.md).

{abstractmemory-0.2.3 → abstractmemory-0.2.5}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Laurent-Philippe Albou
+Copyright (c) 2024 Laurent-Philippe Albou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,6 +19,3 @@ 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.
-
-
-

abstractmemory-0.2.5/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: AbstractMemory
+Version: 0.2.5
+Summary: AbstractMemory: temporal, provenance-aware semantic memory primitives for AbstractFramework.
+Project-URL: AbstractFramework (monorepo), https://github.com/lpalbou/abstractframework
+Author: Laurent-Philippe Albou
+License: MIT
+License-File: LICENSE
+Keywords: agents,knowledge-graph,memory,temporal,triples
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: lancedb; extra == 'all'
+Provides-Extra: all-apple
+Requires-Dist: lancedb; extra == 'all-apple'
+Provides-Extra: all-gpu
+Requires-Dist: lancedb; extra == 'all-gpu'
+Provides-Extra: apple
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: gpu
+Provides-Extra: lancedb
+Requires-Dist: lancedb; extra == 'lancedb'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# AbstractMemory (early / pre-1.0)
+
+AbstractMemory is a small Python library for **append-only, temporal, provenance-aware triple assertions** with **deterministic structured queries** and optional **vector/semantic retrieval**.
+
+## Status
+- This package is early (pre-1.0): the API is intentionally small, and details may evolve.
+- Current repo version: `0.2.4` (see [`pyproject.toml`](pyproject.toml)).
+- Implemented today (public API): `TripleAssertion`, `TripleQuery`, `TripleStore`, `InMemoryTripleStore`, `SQLiteTripleStore`, `LanceDBTripleStore`, `TextEmbedder`, `AbstractGatewayTextEmbedder`.
+  - Source of truth for exports: [`src/abstractmemory/__init__.py`](src/abstractmemory/__init__.py)
+- Requires Python 3.10+ (see [`pyproject.toml`](pyproject.toml))
+- Release-channel note: this checkout is the source of truth for this documentation. As of 2026-05-05, PyPI's `AbstractMemory 0.2.3` has a different source layout from this repository and `origin` only has tags through `v0.2.2`; treat that mismatch as release drift until a maintainer republishes/tags from this repo.
+
+## Ecosystem (AbstractFramework)
+
+AbstractMemory is part of the **AbstractFramework** ecosystem:
+- It stores and retrieves durable “memory” as append-only triples (this package).
+- It can *optionally* call an **AbstractGateway** embeddings endpoint for semantic retrieval via `AbstractGatewayTextEmbedder` (no direct AbstractCore/AbstractRuntime dependency).
+
+Evidence:
+- No direct dependency on AbstractCore/AbstractRuntime: [`pyproject.toml`](pyproject.toml)
+- Gateway adapter implementation: [`src/abstractmemory/embeddings.py`](src/abstractmemory/embeddings.py)
+
+```mermaid
+flowchart LR
+  APP["Your app or agent"] --> AM["AbstractMemory"]
+  AM --> IM["InMemoryTripleStore"]
+  AM --> SQL["SQLiteTripleStore"]
+  AM --> LDB["LanceDBTripleStore"]
+  SQL --> SQLITE[("SQLite file")]
+  LDB --> DISK[("LanceDB on disk")]
+
+  AM -- "optional embeddings" --> GW["AbstractGateway"]
+  GW --> AR["AbstractRuntime"]
+  GW --> AC["AbstractCore"]
+```
+
+Related projects:
+- AbstractFramework: `https://github.com/lpalbou/AbstractFramework`
+- AbstractCore: `https://github.com/lpalbou/abstractcore`
+- AbstractRuntime: `https://github.com/lpalbou/abstractruntime`
+
+## Install
+
+From source (recommended inside the AbstractFramework monorepo):
+
+```bash
+python -m pip install -e .
+```
+
+Optional persistent backend + vector search:
+
+```bash
+python -m pip install -e ".[lancedb]"
+```
+
+PyPI (packaged release):
+
+```bash
+python -m pip install AbstractMemory
+python -m pip install "AbstractMemory[lancedb]"
+```
+
+Framework hardware profile aliases are also available:
+`AbstractMemory[apple]` and `AbstractMemory[gpu]` are no-op compatibility
+extras; `AbstractMemory[all-apple]` and `AbstractMemory[all-gpu]` install the
+LanceDB backend for durable vector-capable recall.
+
+Notes:
+- The distribution name is `AbstractMemory` (pip is case-insensitive). The import name is `abstractmemory`.
+- PyPI releases may not match this repository checkout exactly; see the release-channel note above.
+
+## Quick example
+
+```python
+from abstractmemory import InMemoryTripleStore, TripleAssertion, TripleQuery
+
+store = InMemoryTripleStore()
+store.add(
+    [
+        TripleAssertion(
+            subject="Scrooge",
+            predicate="related_to",
+            object="Christmas",
+            scope="session",
+            owner_id="sess-1",
+            provenance={"span_id": "span_123"},
+        )
+    ]
+)
+
+hits = store.query(TripleQuery(subject="scrooge", scope="session", owner_id="sess-1"))
+assert hits[0].object == "christmas"  # terms are canonicalized (trim + lowercase)
+```
+
+## Documentation
+
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- FAQ: [`docs/faq.md`](docs/faq.md)
+- Architecture (with diagrams): [`docs/architecture.md`](docs/architecture.md)
+- Stores/backends: [`docs/stores.md`](docs/stores.md)
+- API reference: [`docs/api.md`](docs/api.md)
+- Development: [`docs/development.md`](docs/development.md)
+
+## Project
+
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+- License: [`LICENSE`](LICENSE)
+- Acknowledgments: [`ACKNOWLEDGMENTS.md`](ACKNOWLEDGMENTS.md)
+
+## Design principles (v0)
+
+- **Triples-first** representation with temporal fields (`observed_at`, `valid_from`, `valid_until`).
+  - Implemented in `TripleAssertion`: [`src/abstractmemory/models.py`](src/abstractmemory/models.py)
+- **Append-only**: represent updates by adding a new assertion with fresh provenance.
+  - Implemented by all stores: [`src/abstractmemory/in_memory_store.py`](src/abstractmemory/in_memory_store.py), [`src/abstractmemory/sqlite_store.py`](src/abstractmemory/sqlite_store.py), [`src/abstractmemory/lancedb_store.py`](src/abstractmemory/lancedb_store.py)
+- **No direct AbstractCore dependency**: embeddings can be obtained via an AbstractGateway HTTP API.
+  - Implemented by `AbstractGatewayTextEmbedder`: [`src/abstractmemory/embeddings.py`](src/abstractmemory/embeddings.py)