smolAmem 1.0.0__tar.gz

smolamem-1.0.0/.env.example

@@ -0,0 +1,44 @@
+# Example .env file. Copy to `.env` (gitignored) and fill in real values.
+#
+# `tests/conftest.py` loads this on test startup so any test using
+# OpenAIEmbeddings (or any other env-dependent code) just works locally.
+# The library itself never auto-loads dotenv.
+#
+# IMPORTANT — Windows / PowerShell users:
+#   Do NOT create .env with `echo ... > .env`. PowerShell's `>` redirection
+#   writes UTF-16 LE with a BOM, and python-dotenv reads UTF-8. The test
+#   suite will warn and skip key-dependent tests instead of crashing, but
+#   your tests still won't see the key.
+#
+#   Correct ways to create `.env` on Windows:
+#     * Open `.env.example` in VS Code / Notepad, "Save As" -> `.env` with
+#       UTF-8 encoding.
+#     * Or PowerShell with explicit encoding:
+#         Set-Content -Encoding utf8 -Path .env -Value 'OPENAI_API_KEY=sk-...'
+
+# ---------------------------------------------------------------------------
+# OpenAI (embeddings + LLM judge)
+# ---------------------------------------------------------------------------
+
+# Required for OpenAIEmbeddings + OpenAILLMJudge integration tests. Without
+# it the OpenAI-specific tests skip cleanly.
+# Get one at https://platform.openai.com/api-keys.
+OPENAI_API_KEY=sk-...
+
+# ---------------------------------------------------------------------------
+# Backend integration tests (v0.4)
+# ---------------------------------------------------------------------------
+# Setting either of the next two env vars opts that backend into the
+# conformance suite. With neither set, qdrant + pgvector tests skip and
+# memory + sqlite still run normally.
+#
+# To spin both services up locally:
+#     docker compose up -d
+#
+# Then uncomment the lines below.
+
+# Qdrant: default REST endpoint exposed by docker-compose.yml.
+# MNEME_TEST_QDRANT_URL=http://localhost:6333
+
+# pgvector: connection string matching docker-compose.yml's defaults.
+# MNEME_TEST_PGVECTOR_DSN=postgresql://mneme:mneme@localhost:5433/mneme

smolamem-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+# Build + deploy the mkdocs-material site to GitHub Pages.
+#
+# Runs on every push to main of the public mirror repo. The private dev repo
+# uses the same workflow file (it's part of the published tree) but won't
+# have Pages enabled, so the deploy step no-ops there if the GITHUB_PAGES
+# environment isn't configured. To enable for a fresh fork:
+#
+#   1. Settings -> Pages -> Source: "GitHub Actions"
+#   2. Push to main. The workflow takes over from there.
+name: Build docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Only one in-flight docs build at a time; cancel any superseded run.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      # Install the project with the [docs] extra. mkdocstrings autogen needs
+      # the package importable, so we install + the extra in one shot.
+      - name: Install project + docs deps
+        run: uv sync --extra docs
+
+      - name: Build site
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

smolamem-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,150 @@
+# Build a wheel + sdist and publish to PyPI via trusted publishing (OIDC).
+#
+# Triggers on tags matching ``v*`` pushed to the repo. No long-lived API
+# token is stored anywhere — PyPI verifies the OIDC token GitHub Actions
+# issues and authorises the upload directly.
+#
+# One-time PyPI setup (done in the PyPI web UI, not here):
+#
+#   1. Create an account at https://pypi.org/account/register/ if you
+#      don't have one.
+#   2. Go to https://pypi.org/manage/account/publishing/ and add a
+#      "pending publisher":
+#          - PyPI Project Name:  smolAmem
+#          - Owner:              AshwinUgale
+#          - Repository name:    ashwinugale-mneme
+#          - Workflow name:      release.yml
+#          - Environment name:   pypi      (must match the `environment:` below)
+#   3. The first time this workflow runs successfully, PyPI creates the
+#      real project and removes the "pending" status. Subsequent releases
+#      use the same publisher config without any further setup.
+#
+# Cutting a release:
+#
+#   git tag v1.0.0
+#   git push private --tags     # (your private remote)
+#   ./.cowork/publish.sh "v1.0.0"   # also push to the public mirror
+#   # then on the PUBLIC mirror repo, create a tag matching the version:
+#   #   git tag v1.0.0
+#   #   git push origin v1.0.0
+#   # That tag push fires this workflow.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Verify tag matches package version
+        run: |
+          set -e
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(uv run --no-project python -c '
+          import tomllib, pathlib
+          print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])
+          ')"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::tag $TAG_VERSION does not match pyproject version $PKG_VERSION"
+            exit 1
+          fi
+          echo "tag and pyproject agree on version $PKG_VERSION"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: List build artifacts
+        run: ls -la dist/
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment name MUST match what's registered as the
+    # trusted-publisher environment in PyPI's "pending publisher"
+    # config. PyPI will reject the upload otherwise.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/smolAmem
+    permissions:
+      # id-token: write is what lets GitHub mint the OIDC token PyPI
+      # uses to authenticate. contents: read is the default.
+      id-token: write
+      contents: read
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # No `password:` / `user:` — trusted publishing handles auth.
+          # `verbose: true` makes the upload log show why if it fails.
+          verbose: true
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          body: |
+            See [CHANGELOG.md](./CHANGELOG.md) for what's in this release.
+
+            Install:
+
+                pip install smolAmem==${{ github.ref_name }}
+
+            (the leading `v` is dropped from the version in `pip` install lines)
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz

smolamem-1.0.0/.gitignore

@@ -0,0 +1,82 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# uv
+.venv/
+.uv-cache/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.cache/
+
+# Mypy / ruff
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+
+# Type checker
+.pyre/
+.pytype/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Claude Code local config / memory (machine-local, never commit)
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets / local env
+.env
+.env.*
+!.env.example
+*.local
+
+# SQLite databases created during dev/eval
+*.sqlite
+*.sqlite3
+*.db
+
+# Eval artifacts (results get checked in selectively, not blanket)
+.eval-cache/
+out/
+
+# mkdocs build output
+site/
+
+# NOTE: .cowork/ is intentionally NOT gitignored.
+# It contains private dev context that we want versioned in the PRIVATE repo.
+# It is excluded from the PUBLIC repo via .cowork/publish.sh.

smolamem-1.0.0/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from `1.0.0` onward.
+
+> **Naming note:** install with `pip install smolAmem`; import as `import mneme`. Two-name pattern (same as Pillow/PIL) because `mneme` was already taken on PyPI when this library was published.
+
+## [Unreleased]
+
+(empty)
+
+## [1.0.0] — 2026-05-23
+
+First stable release. Public APIs are now under semver; minor bumps add features without breaking, patch bumps fix bugs, major bumps will be rare and pre-announced.
+
+### Added
+- PyPI release as `smolAmem`. Install with `pip install smolAmem`; import name stays `mneme`.
+- `Development Status :: 5 - Production/Stable` classifier.
+- `CHANGELOG.md` (this file).
+- GitHub Actions release workflow that builds + publishes to PyPI via OIDC trusted publishing (no long-lived API token).
+
+### Changed
+- Dropped pre-alpha warnings from README and docs landing page.
+
+## [0.8.0] — 2026-05-23
+
+Integration validation. No new features — every previously env-skipped backend test is now actually executed against real Qdrant + pgvector containers, and an end-to-end smoke script proves the full lifecycle works with real OpenAI.
+
+### Added
+- `scripts/smoke.py` — end-to-end smoke test that wires `MemoryManager` + real `OpenAIEmbeddings` + real `OpenAILLMJudge` against the chosen backend and walks through write → retrieve → consolidate → retrieve → forget. `--backend {sqlite,qdrant,pgvector}`.
+- `scripts/check.ps1` — Windows-native full check pipeline wrapper (ruff + format + mypy + pytest + `mkdocs build --strict`).
+- `.cowork/publish.ps1` — Windows-native equivalent of `publish.sh` using `robocopy` instead of `rsync`.
+- Qdrant payload indexes on `created_at` (DATETIME, required by `order_by`), `agent_id` and `tier` (KEYWORD, performance) created during `_ensure_collection`.
+
+### Fixed
+- `QdrantBackend.list_recent()` no longer crashes with `"No range index for order_by key: created_at"`. Caused by missing payload index; now created at construction time.
+- `QdrantBackend.touch()` no longer crashes on IDs that aren't valid hex UUIDs. Now silently skips them, matching the existing `get()` / `delete()` "unknown id" contract.
+
+### Changed
+- README + docs lead with the OpenAI-embedder benchmark (`recall@5 = 1.000` at 67.7 tokens/test point) and keep the HashEmbedder row as the no-API-key deterministic baseline.
+
+## [0.7.0] — 2026-05-22
+
+Public documentation site.
+
+### Added
+- `[docs]` extra: mkdocs, mkdocs-material, mkdocstrings[python], pymdown-extensions.
+- `mkdocs.yml` at repo root (Material theme, indigo palette, full feature set).
+- Eight hand-written documentation pages under `docs/`: index, quickstart, concepts, backends, embedders, adapters, eval, api.
+- `docs/api.md` autogenerated from docstrings via mkdocstrings (Google docstring style, source-order members, filtered to public symbols).
+- `.github/workflows/docs.yml` — build + deploy to GitHub Pages on push to main via `actions/upload-pages-artifact@v3` + `actions/deploy-pages@v4`. `mkdocs build --strict` so any warning fails the build.
+
+### Changed
+- README rewritten with badges, concise pitch, install/quickstart snippet, and links to the live docs site.
+
+## [0.6.0] — 2026-05-22
+
+Eval harness.
+
+### Added
+- `evals/` sibling directory at repo root (not shipped in the wheel).
+- `evals/schema.py` — Pydantic models for the corpus shape (`Conversation`, `Turn`, `TestPoint`).
+- `evals/corpus/` with five labelled starter conversations covering long-range preference recall, contradiction handling (newer-wins), multi-fact retrieval, in-flight tasks, and multi-fact recall queries.
+- `evals/baselines/` — `MemoryStrategy` Protocol plus three reference strategies: `NoMemoryStrategy` (floor), `SummaryBufferStrategy` (LangChain-style rolling summary), `FullHistoryStrategy` (oracle ceiling).
+- `evals/runners/base.py::EvalRunner` orchestrator + `evals/runners/mneme.py` adapter.
+- `evals/metrics/recall.py::recall_at_k` and `evals/metrics/tokens.py::token_cost_summary` — both pure functions over `RunResult`.
+- `python -m evals` CLI with flags `--corpus`, `--runner`, `--backend`, `--embedder`, `--output`, `--seed`, `--k`. `--with-answers` / `--judge` reserved for future LLM-judged accuracy.
+- `tests/test_eval_harness.py` end-to-end coverage of all four strategies plus the CLI.
+
+## [0.5.0] — 2026-05-21
+
+Framework adapters.
+
+### Added
+- `mneme.adapters.MnemeChatMessageHistory` — subclass of LangChain's `BaseChatMessageHistory`. Dual-writes to working + episodic by default; `also_persist_episodic=False` for ephemeral chat.
+- `mneme.adapters.MnemeLlamaIndexMemory` — subclass of LlamaIndex's `BaseMemory`. Same dual-write semantics.
+- `mneme.adapters.context_for()` — raw-OpenAI helper returning `messages=[...]` with retrieved memory as a `system` block (with `[FACT id=...]` / `[EPISODE id=...]` citation markers) plus working-memory turns. Optional `token_budget` packs to a tiktoken (`cl100k_base`) count.
+- Three optional extras: `[langchain]`, `[llamaindex]`, `[tokens]`.
+- PEP 562 lazy submodule loading in `mneme.adapters.__init__` so users only pay for the framework deps they actually use.
+
+## [0.4.0] — 2026-05-21
+
+Production-grade backends.
+
+### Added
+- `mneme.QdrantBackend` — one Qdrant collection per backend instance; multi-tenancy via `agent_id` payload filter; cosine distance; UUID round-trip at the boundary.
+- `mneme.PgVectorBackend` — psycopg3 sync, pgvector extension, `<=>` cosine operator. Schema mirrors `SQLiteBackend`.
+- Conformance suite (`tests/test_backends.py`) now parametrises over `["memory", "sqlite", "qdrant", "pgvector"]`. Env-gated via `MNEME_TEST_QDRANT_URL` / `MNEME_TEST_PGVECTOR_DSN`.
+- `docker-compose.yml` at repo root for local Qdrant + pgvector services.
+- Two new extras: `[qdrant]`, `[pgvector]`.
+
+## [0.3.0] — 2026-05-21
+
+Forgetting + scheduled background work.
+
+### Added
+- `MemoryRecord.expires_at` — UTC datetime, default `None`. Round-trips through every backend.
+- `MnemeBackend.touch(record_ids, *, now)` — persists access count + last-accessed timestamp.
+- `retrieve()` calls `backend.touch()` on the returned top-k and defensively filters records with `expires_at <= now`.
+- `MemoryManager.forget(*, now, ttl_only, access_floor, cold_age_days, max_per_tier)` — two-phase: TTL eviction, then access-frequency decay. Walks `(EPISODIC, SEMANTIC)`; working memory untouched.
+- `MemoryManager.start_scheduler()` / `stop_scheduler()` — APScheduler `BackgroundScheduler` integration. `max_instances=1, coalesce=True` on both jobs.
+- New `[scheduler]` extra: `apscheduler>=3.10`.
+
+## [0.2.0] — 2026-05-21
+
+Real consolidation. Episodic → semantic pipeline driven by an LLM judge.
+
+### Added
+- `mneme.LLMJudge` Protocol + `OpenAILLMJudge` (uses `response_format={"type":"json_schema","strict":true}`) + `MockLLMJudge` (handler callable + call log for tests).
+- `MemoryManager.consolidate(*, since, batch_size, dedup_threshold, max_episodes)` — reads recent episodes, batches them, asks the judge to extract durable facts, dedups against existing semantic facts via cosine similarity (newer-wins-with-provenance merge).
+- `MnemeBackend.list_recent(*, agent_id, tier, since, limit)` added to the protocol.
+
+## [0.1.0] — 2026-05-21
+
+Walking skeleton. The library does something end-to-end.
+
+### Added
+- `mneme.MemoryTier` enum + `MemoryRecord` base + `WorkingMemory` / `EpisodicMemory` / `SemanticFact` subclasses.
+- `mneme.MnemeBackend` Protocol + reference `InMemoryBackend`.
+- `mneme.SQLiteBackend` using sqlite-vec via a `vec0` virtual table joined by rowid.
+- `mneme.EmbeddingProvider` Protocol + `OpenAIEmbeddings` (defaults to `text-embedding-3-small`) + `HashEmbedder` (deterministic, no-key test double).
+- Three tier classes (`WorkingMemoryTier`, `EpisodicMemoryTier`, `SemanticMemoryTier`).
+- `MemoryManager` facade exposing `.working`, `.episodic`, `.semantic` as attributes and a single `retrieve(query, *, k, tiers, authority_weights, half_life_days, use_confidence, now)` with multiplicative score fusion (similarity × authority × recency × confidence).
+
+[unreleased]: https://github.com/ashwinugale/ashwinugale-mneme/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v1.0.0
+[0.8.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.8.0
+[0.7.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.7.0
+[0.6.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.6.0
+[0.5.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.5.0
+[0.4.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.4.0
+[0.3.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.3.0
+[0.2.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.2.0
+[0.1.0]: https://github.com/ashwinugale/ashwinugale-mneme/releases/tag/v0.1.0

smolamem-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashwin Ugale
+
+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.

smolamem-1.0.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: smolAmem
+Version: 1.0.0
+Summary: Multi-tier long-term memory for LLM agents. Install: pip install smolAmem. Import: import mneme.
+Project-URL: Homepage, https://ashwinugale.github.io/ashwinugale-mneme/
+Project-URL: Documentation, https://ashwinugale.github.io/ashwinugale-mneme/
+Project-URL: Repository, https://github.com/ashwinugale/ashwinugale-mneme
+Project-URL: Issues, https://github.com/ashwinugale/ashwinugale-mneme/issues
+Author-email: Ashwin Ugale <ugaleashwin@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,llm,memory,rag,vector-search
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.11; extra == 'llamaindex'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Provides-Extra: pgvector
+Requires-Dist: pgvector>=0.3; extra == 'pgvector'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'pgvector'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.12; extra == 'qdrant'
+Provides-Extra: scheduler
+Requires-Dist: apscheduler>=3.10; extra == 'scheduler'
+Provides-Extra: sqlite
+Requires-Dist: sqlite-vec>=0.1.6; extra == 'sqlite'
+Provides-Extra: tokens
+Requires-Dist: tiktoken>=0.7; extra == 'tokens'
+Description-Content-Type: text/markdown
+
+# Mneme
+
+> Multi-tier long-term memory for LLM agents. Working / episodic / semantic tiers, pluggable storage backends, framework-agnostic adapters, and explicit forgetting + consolidation.
+
+[![docs](https://img.shields.io/badge/docs-ashwinugale.github.io%2Fashwinugale--mneme-blue)](https://ashwinugale.github.io/ashwinugale-mneme/)
+[![python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+**Status:** 1.0 released. APIs are stable; semver from here. Bug reports welcome.
+
+## Why
+
+Every agent framework ships with toy memory: last-N messages, or an LLM-summarised buffer. Real agents need to remember user preferences across weeks, recall specific past interactions, and store semantic facts extracted from many interactions — and they need to forget things that stop being relevant.
+
+Mneme is the library you wish existed.
+
+## Install
+
+```bash
+pip install smolAmem                    # core only
+pip install "smolAmem[sqlite,openai]"   # SQLite + OpenAI embeddings
+pip install "smolAmem[qdrant,openai]"   # production vector backend
+```
+
+> **Heads-up on naming:** PyPI install name is `smolAmem` (the `mneme` slot was already taken). Python import name stays `mneme` — same dual-name pattern as `Pillow` / `PIL` or `pyyaml` / `yaml`. So you `pip install smolAmem` but write `import mneme` everywhere in your code.
+
+## Quickstart
+
+```python
+from mneme import MemoryManager, SQLiteBackend, OpenAIEmbeddings
+
+m = MemoryManager(
+    agent_id="alice",
+    backend=SQLiteBackend(path="mneme.db", dimensions=1536),
+    embedder=OpenAIEmbeddings(),
+)
+
+m.episodic.add("user mostly works in TypeScript", metadata={"role": "user"})
+
+for r in m.retrieve("what language does the user prefer?", k=3):
+    print(r.score, r.record.content)
+```
+
+Full walkthrough: [docs/quickstart](https://ashwinugale.github.io/ashwinugale-mneme/quickstart/).
+
+## Documentation
+
+The full site lives at **[ashwinugale.github.io/ashwinugale-mneme](https://ashwinugale.github.io/ashwinugale-mneme/)**.
+
+- [Concepts](https://ashwinugale.github.io/ashwinugale-mneme/concepts/) — the three-tier model, retrieval, consolidation, forgetting.
+- [Backends](https://ashwinugale.github.io/ashwinugale-mneme/backends/) — InMemory, SQLite, Qdrant, pgvector.
+- [Adapters](https://ashwinugale.github.io/ashwinugale-mneme/adapters/) — LangChain, LlamaIndex, raw OpenAI.
+- [Eval harness](https://ashwinugale.github.io/ashwinugale-mneme/eval/) — reproducible recall@k + token-cost benchmark.
+- [API reference](https://ashwinugale.github.io/ashwinugale-mneme/api/) — autogen from docstrings.
+
+## Benchmark snapshot
+
+From the v0.6 [eval harness](https://ashwinugale.github.io/ashwinugale-mneme/eval/) on the 5-conversation starter corpus, k=5:
+
+| Strategy | recall@5 | tokens / test point |
+|---|---|---|
+| `no_memory` | 0.000 | 0.0 |
+| `mneme` (hash, deterministic) | 0.833 | 68.0 |
+| **`mneme` (OpenAI embeddings)** | **1.000** | **67.7** |
+| `full_history` | 1.000 | 141.0 |
+| `summary_buffer` | 1.000 | 165.3 |
+
+Mneme matches the full-history oracle for accuracy at **less than half** the token cost. The HashEmbedder row is the cheap deterministic baseline that runs without an API key — useful in CI and for reviewers reproducing numbers.
+
+Reproduce:
+
+```bash
+uv run python -m evals --runner mneme --embedder openai --output out/mneme.json
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).