memlord 0.2.3__tar.gz

memlord-0.2.3/.dockerignore

@@ -0,0 +1,12 @@
+.venv
+.git
+__pycache__
+*.pyc
+*.pyo
+.env
+*.db
+*.db-shm
+*.db-wal
+.pytest_cache
+.mypy_cache
+data/

memlord-0.2.3/.env.example

@@ -0,0 +1,28 @@
+# ── Database ──────────────────────────────────────────────────────────────────
+MEMLORD_DB_URL=postgresql+asyncpg://postgres:postgres@postgres/memlord
+
+# ── ONNX model ────────────────────────────────────────────────────────────────
+# Directory containing model.onnx and tokenizer.json.
+MEMLORD_MODEL_DIR=/app/src/memlord/onnx
+
+# ── Server ────────────────────────────────────────────────────────────────────
+MEMLORD_HOST=0.0.0.0
+MEMLORD_PORT=8000
+
+# ── Search tuning ─────────────────────────────────────────────────────────────
+# MEMLORD_RRF_K=60
+# MEMLORD_DEFAULT_LIMIT=10
+# MEMLORD_SIM_THRESHOLD=0.7
+# MEMLORD_DEDUP_THRESHOLD=0.95
+
+# ── OAuth 2.1 ─────────────────────────────────────────────────────────────────
+# MEMLORD_BASE_URL=http://localhost:8000
+# MEMLORD_OAUTH_JWT_SECRET=change-me-to-a-long-random-secret
+
+# ── Email / SMTP ───────────────────────────────────────────────────────────────
+# MEMLORD_SMTP_HOST=smtp.resend.com
+# MEMLORD_SMTP_PORT=587
+# MEMLORD_SMTP_USER=resend
+# MEMLORD_SMTP_PASSWORD=re_xxxxxxxxxxxx
+# MEMLORD_SMTP_FROM=noreply@example.com
+# MEMLORD_SMTP_TLS=true

memlord-0.2.3/.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint & type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --dev
+      - run: uv run black --check .
+
+  migrations:
+    name: Migration check
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    env:
+      MEMLORD_DB_URL: postgresql+asyncpg://postgres:postgres@localhost/postgres
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --dev
+      - run: uv run alembic upgrade head
+      - run: uv run alembic-autogen-check
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    env:
+      MEMLORD_MODEL_DIR: src/memlord/onnx
+      MEMLORD_DB_URL: postgresql+asyncpg://postgres:postgres@localhost/postgres
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/cache@v4
+        with:
+          path: src/memlord/onnx
+          key: onnx-model-v1
+      - run: uv sync --dev
+      - run: uv run python scripts/download_model.py
+      - run: uv run pytest tests/ -x -q
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [lint, migrations, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/memlord
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: [lint, migrations, test]
+    if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Image name
+        run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+      - name: Resolve version
+        id: version
+        run: |
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            echo "value=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=0.0.0" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: VERSION=${{ steps.version.outputs.value }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

memlord-0.2.3/.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+*.db
+data/
+.mcp.json

memlord-0.2.3/.mcp.json.example

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "memlord-local": {
+      "command": "python",
+      "args": [
+        "src/memlord/main.py",
+        "--stdio"
+      ],
+      "env": {
+        "MEMLORD_DB_URL": "postgresql+asyncpg://postgres:postgres@localhost/memlord",
+        "MEMLORD_STDIO_USER_ID": "1"
+      }
+    },
+    "memlord-cloud": {
+      "type": "http",
+      "url": "http://app.memlord.com/mcp"
+    }
+  }
+}

memlord-0.2.3/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run migrations
+alembic upgrade head
+
+# Create a new migration (autogenerate)
+alembic revision --autogenerate -m "description"
+
+# Check migrations are up to date (CI)
+alembic-autogen-check
+
+# Run the server
+memlord
+
+# Type check
+pyright src/
+
+# Format
+black .
+
+# Run tests
+pytest
+
+# Run a single test
+pytest tests/path/test_file.py::test_name -x
+```
+
+## Architecture
+
+**Memlord** is an MCP memory server with hybrid BM25 + vector search, backed by PostgreSQL + pgvector.
+
+**Request path:** FastAPI app (root `/`) mounts FastMCP at `/mcp`. Single uvicorn process, single port. OAuth 2.1 is optional — enabled only when all three are set: `MEMLORD_OAUTH_JWT_SECRET`, `MEMLORD_OAUTH_PASSWORD`, `MEMLORD_BASE_URL`.
+
+**Search pipeline:** query → parallel BM25 (`search_vector @@ websearch_to_tsquery`) + vector KNN (`embedding <=>`, cosine distance) → Reciprocal Rank Fusion (`rrf = 1/(k+rank_bm25) + 1/(k+rank_vec)`, k=60) → top-N.
+
+**Embedding pipeline:** `content` → tokenizer.json → ONNX inference (all-MiniLM-L6-v2) → mean pooling with attention mask → L2 normalize → `float32[384]` stored as `vector(384)` column in `memories`.
+
+**DB sync:** `search_vector` is a `TSVECTOR GENERATED ALWAYS AS (to_tsvector('simple', content)) STORED` computed column — updated automatically by PostgreSQL. `embedding` is updated manually by the application on write.
+
+## Key Conventions
+
+**SQLAlchemy usage:** Core queries only — no ORM relationships (`relationship`), no lazy loading. Queries are written with `select()`, `insert()`, etc. Use `sa.text()` only for PostgreSQL-specific syntax that cannot be expressed via Core. Use `.mappings().all()` for multi-column row results — access by column name, not index. Sessions used as async context managers via `session()` (general use) or `SessionDep` (FastAPI dependency). **Never call `commit()` or `rollback()` manually** — `session()` commits on success and rolls back on exception automatically.
+
+**Vector parameters:** Pass `list[float]` directly — `Vector(384).bind_processor` converts to `'[v1,v2,...]'` string, asyncpg sends as text, PostgreSQL casts server-side. Do NOT use `register_vector` (causes codec conflict with bind_processor). Do NOT manually format vec strings.
+
+**FastMCP tool structure:** Each tool file defines its own `mcp = FastMCP()` and registers tools with `@mcp.tool`. `tools/__init__.py` re-exports each `mcp` instance. `server.py` mounts them via `mcp.mount()`. Sessions injected via `s: AsyncSession = SessionDep  # type: ignore[assignment]` using `fastmcp.dependencies.Depends`.
+
+**Model style:** Models are defined with `import sqlalchemy as sa` and classical `sa.Column(...)` — no `Mapped`, no `mapped_column`, no type annotations on columns, no `from __future__ import annotations`, no `__all__`.
+
+**Structured data:** Use Pydantic `BaseModel` for structured objects — no `dataclass`.
+
+**Alembic engine:** `migrations/env.py` uses `create_async_engine` with asyncpg and runs migrations via `asyncio.run()`. No sync driver needed — pgvector is a server-side extension, no client-side loading required.
+
+**No logic in `__init__.py`:** All logic lives in dedicated modules. `__init__.py` files are re-exports only.
+
+**Config prefix:** All env vars use `MEMLORD_` prefix. `.env` file is supported.
+
+**ONNX model files** (`src/memlord/onnx/model.onnx`, `tokenizer.json`) are excluded from git. Download before running: `uv run python scripts/download_model.py`. Downloaded from `sentence-transformers/all-MiniLM-L6-v2` on HuggingFace.
+
+## Project Layout
+
+```
+src/memlord/
+├── config.py          # pydantic-settings, MEMLORD_* env vars
+├── db.py              # async SQLAlchemy engine (asyncpg)
+├── embeddings.py      # ONNX session, tokenize, mean pool, L2 norm
+├── search.py          # BM25 + vector KNN + RRF fusion (PostgreSQL Core queries)
+├── oauth.py           # custom OAuthProvider (fastmcp.server.auth)
+├── main.py            # FastAPI app + mount MCP + uvicorn entrypoint
+├── models/            # table definitions (no relationships)
+├── schemas/           # Pydantic request/response schemas
+├── tools/             # one file per MCP tool
+├── ui/                # web UI (FastAPI routers)
+│   ├── __init__.py    # assembles ui_router from sub-routers
+│   ├── base.py        # pages: index, search, memory detail, update, delete
+│   ├── data.py        # export/import JSON (uses ImportItem schema)
+│   ├── login.py       # login form (GET/POST /ui/login)
+│   └── utils.py       # templates, session_token, require_auth
+└── onnx/              # model.onnx + tokenizer.json (committed)
+migrations/
+├── env.py             # async alembic env (asyncpg)
+└── versions/          # migrations
+```