Phase 0 scaffold: package skeleton, tooling, CI with coverage

.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies (locked)
+        run: uv sync --locked --python ${{ matrix.python-version }}
+
+      - name: Ruff lint
+        run: uv run ruff check src/
+
+      - name: Ruff format check
+        run: uv run ruff format --check src/
+
+      - name: Pyright type check
+        run: uv run pyright src/ --pythonversion ${{ matrix.python-version }}
+
+      - name: Tests (with coverage)
+        run: uv run pytest src/tests -v --tb=short --cov --cov-report=term
+        env:
+          COVERAGE_FILE: .coverage.${{ matrix.python-version }}
+
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+
+  coverage:
+    name: Coverage report
+    runs-on: ubuntu-latest
+    needs: checks
+    permissions:
+      pull-requests: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download coverage data
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+
+      - name: Coverage comment + badge
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+          MERGE_COVERAGE_FILES: true

.gitignore

@@ -1,3 +1,13 @@
 .idea/
 _additional_context/
 _feature_planning/
+
+# python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+.coverage*
+htmlcov/

Makefile

@@ -5,3 +5,22 @@ claude:
 .PHONY: claudecontinue
 claudecontinue:
 	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_AUTO_MODE=1 claude --dangerously-skip-permissions --continue --remote-control
+
+# --- development ---
+.PHONY: install lint format typecheck test check
+install:
+	uv sync
+
+lint:
+	uv run ruff check src/
+
+format:
+	uv run ruff format src/
+
+typecheck:
+	uv run pyright src/
+
+test:
+	uv run pytest src/tests -v --tb=short --cov --cov-report=term
+
+check: lint typecheck test

README.md

@@ -1,14 +1,17 @@
 # Ultimate Memory
 
+[![CI](https://github.com/writeitai/ultimate-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/writeitai/ultimate-memory/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/writeitai/ultimate-memory/python-coverage-comment-action-data/endpoint.json)](https://github.com/writeitai/ultimate-memory/tree/python-coverage-comment-action-data)
+
 A memory system for AI agents, designed to ingest **millions** of heterogeneous documents and
 distill them into progressively more abstract, navigable knowledge — while keeping everything
 auditable by humans. Scale is a requirement, not an aspiration: it is meant to still be useful
 at a million documents.
 
-> **⚠️ This repository is in the research and design phase. It contains documents, not code.**
-> There is nothing to build or run yet. What lives here is the thinking — requirements,
-> architecture, research, decisions, and the open questions — that has to be settled *before*
-> implementation. If you're looking for a working library, it isn't here yet.
+> **⚠️ Implementation has just begun; there is nothing usable yet.** The design came first and
+> lives here in full — requirements, architecture, research, decisions, and the open questions.
+> The build follows [plan/plans/roadmap.md](plan/plans/roadmap.md) (phase 0 is under way). If
+> you're looking for a working library, it isn't here yet.
 
 ## TL;DR
 

pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ultimate-memory"
+version = "0.1.0"
+description = "A layered, scale-oriented memory system for AI agents."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    { name = "WriteIt.ai s.r.o.", email = "info@writeit.ai" },
+]
+keywords = [
+    "ai",
+    "agents",
+    "memory",
+    "knowledge",
+    "evidence",
+    "bitemporal",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.11",
+]
+
+[project.urls]
+Homepage = "https://github.com/writeitai/ultimate-memory"
+Repository = "https://github.com/writeitai/ultimate-memory"
+Issues = "https://github.com/writeitai/ultimate-memory/issues"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+    "pytest-cov>=6.0",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ultimate_memory"]
+
+# Ruff config copied from the writeitai house style (team-harness / loopy-loop).
+[tool.ruff]
+src = ["src"]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.format]
+skip-magic-trailing-comma = true
+
+[tool.ruff.lint]
+extend-select = ["I", "B", "A", "ERA"]
+
+[tool.ruff.lint.isort]
+case-sensitive = false
+force-single-line = true
+force-sort-within-sections = true
+known-first-party = ["ultimate_memory"]
+order-by-type = false
+relative-imports-order = "closest-to-furthest"
+section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
+
+# Deliberate deviation from the team-harness/loopy-loop template: they run pyright in
+# "basic" mode with ~20 report* checks disabled. This is a data-integrity system (enums,
+# validity windows, adjudication outcomes), so library code runs "standard" (NOT strict —
+# the noisy reportUnknown* family is off) with no checks disabled.
+#
+# Relax-with-receipts rule: any future report*=false here MUST carry a one-line reason
+# comment and come from observed friction on real code, never pre-emptively. Loosening
+# later is a one-line change; tightening later means fixing accumulated violations.
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+include = ["src"]
+extraPaths = ["src"]
+exclude = ["**/.venv", "**/virtualenvs", "tmp/"]
+
+# Test code has different ergonomics (poking internals, monkeypatching) — relaxed
+# per-directory, so src/ultimate_memory stays at full standard.
+[[tool.pyright.executionEnvironments]]
+root = "src/tests"
+reportPrivateUsage = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = ["src"]
+testpaths = ["src/tests"]
+
+[tool.coverage.run]
+source = ["src/ultimate_memory"]
+branch = true
+relative_files = true # required by the coverage-comment action
+
+[tool.coverage.report]
+show_missing = true
+precision = 1

src/tests/test_smoke.py

@@ -0,0 +1,14 @@
+"""Phase-0 smoke tests: the package imports, is versioned, and ships its type marker."""
+
+from importlib.resources import files
+
+import ultimate_memory
+
+
+def test_package_imports_and_has_version() -> None:
+    assert isinstance(ultimate_memory.__version__, str)
+    assert ultimate_memory.__version__ != ""
+
+
+def test_package_ships_py_typed_marker() -> None:
+    assert files("ultimate_memory").joinpath("py.typed").is_file()

src/ultimate_memory/__init__.py

@@ -0,0 +1,13 @@
+"""ultimate-memory: a layered, scale-oriented memory system for AI agents.
+
+"ultimate-memory" is the working title; the public name is decided before release
+(see questions.md #11a).
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+
+try:
+    __version__ = version("ultimate-memory")
+except PackageNotFoundError:  # running from a checkout without installation
+    __version__ = "0.0.0+uninstalled"

src/ultimate_memory/py.typed

@@ -0,0 +1 @@
+