memry 0.2.0__tar.gz

memry-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# memry data
+*.db
+*.db-wal
+*.db-shm
+.memry/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# Env
+.env
+.env.*
+!.env.example
+
+# Personal, machine-specific notes
+*.local.md
+.remember/

memry-0.2.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Memry contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

memry-0.2.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: memry
+Version: 0.2.0
+Summary: The open, self-hostable memory layer for AI agents. MCP-native, local-first, research-grade.
+Project-URL: Homepage, https://memry.tech
+Project-URL: Repository, https://github.com/cosmin-novac/memry
+Project-URL: Documentation, https://github.com/cosmin-novac/memry/tree/main/docs
+Author: Memry contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,llm,mcp,memory,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Provides-Extra: ann
+Requires-Dist: usearch>=2.12; extra == 'ann'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mem0
+Requires-Dist: mem0ai>=0.1.100; extra == 'mem0'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# Memry
+
+**[memry.tech](https://memry.tech)** - the open, self-hostable memory layer for AI agents. One `pip install`, zero services,
+plugged into any agent over MCP - with the intelligence layer (extraction, reconciliation,
+temporal invalidation, decay, context construction) as first-class, replaceable research code.
+
+```
+pip install memry
+memry mcp          # ← your agent now has long-term memory
+```
+
+- **MCP-native** - works with Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and any
+  other MCP client, over stdio or streamable HTTP.
+- **Local-first** - a single SQLite file. No vector DB, no Postgres, no cloud. Works with
+  **zero API keys** (FTS5 BM25 + deterministic hash embeddings), gets smarter the moment you
+  set `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`.
+- **Real memory, not a vector dump** - LLM extraction distills conversations into discrete
+  facts; reconciliation deduplicates, merges, and **supersedes contradicted memories instead
+  of deleting them** (bi-temporal: `valid_from` / `invalid_at` / `superseded_by`).
+- **Explainable retrieval** - hybrid vector + BM25 with reciprocal-rank fusion, boosted by
+  recency and importance; every result carries its score signals.
+- **Provenance & audit** - raw episodes are stored immutably; every memory links to its
+  source episodes; every mutation is an event you can inspect (`history`).
+- **Forgetting built in** - importance decays with a half-life; a decay sweep soft-forgets
+  stale trivia (invalidated, never destroyed).
+- **Entities, disambiguated** - mentions become first-class entities, and a name match is
+  never enough to merge: unclear cases stay separate ("three Jonases") with a merge
+  proposal you (or the system, once evidence is clear) confirm or reject later.
+- **Category filters** - `search(categories=["diet"])`, `memry search -c diet`,
+  `?categories=` on REST, `categories` on the MCP search tool.
+- **Scales when you need it** - optional usearch HNSW index (`memry[ann]`) for vector
+  search at scale, and a PostgreSQL + pgvector backend (`memry[postgres]`) for
+  multi-writer deployments. SQLite stays the zero-ops default.
+- **Multi-tenant ready** - per-tenant API keys with transparent namespacing and strict
+  isolation on the self-hosted server (`MEMRY_TENANTS`), plus an admin key.
+- **Research-grade** - a built-in eval harness (recall@k, MRR, latency) with a synthetic
+  dataset, plus a pluggable backend interface with an optional [Mem0](https://github.com/mem0ai/mem0)
+  adapter so you can benchmark against it under identical conditions.
+
+Apache-2.0. Your agents. Your memories. Your infrastructure.
+
+---
+
+## Quickstart
+
+### 1. As an MCP server (any agent)
+
+```jsonc
+// Claude Desktop / Cursor / Windsurf config
+{
+  "mcpServers": {
+    "memry": {
+      "command": "memry",
+      "args": ["mcp"],
+      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }   // optional but recommended
+    }
+  }
+}
+```
+
+```bash
+# Claude Code
+claude mcp add memry -- memry mcp
+```
+
+The server exposes: `save_memories`, `search_memories`, `get_memory_context`,
+`list_memories`, `update_memory`, `delete_memory`, `memory_history`, `memory_stats`.
+
+### 2. As a Python library
+
+```python
+from memry import MemoryStore
+
+store = MemoryStore()
+
+# write: extraction + reconciliation (or infer=False to store verbatim)
+store.add(
+    [{"role": "user", "content": "I'm Ada, a data engineer in Berlin. I prefer uv over pip."}],
+    user_id="ada",
+)
+
+# read: hybrid search with explainable scores
+for hit in store.search("what tooling does the user prefer?", user_id="ada"):
+    print(hit.score, hit.memory.content, hit.signals)
+
+# or a ready-to-inject, token-budgeted context block
+ctx = store.reconstruct_context("help me set up a new project", user_id="ada", token_budget=1200)
+print(ctx.text)
+```
+
+### 3. Self-hosted server (REST + dashboard + MCP)
+
+```bash
+memry serve --host 0.0.0.0 --port 8787
+# dashboard:  http://localhost:8787/
+# REST API:   http://localhost:8787/api/v1/...
+# MCP (HTTP): http://localhost:8787/mcp
+```
+
+Or with Docker:
+
+```bash
+docker compose up -d      # see docker-compose.yml
+```
+
+Or on a fresh VPS (Ubuntu/Debian) with automatic HTTPS - one command, any
+provider ([guide](docs/deploy-vps.md)):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/cosmin-novac/memry/main/deploy/install.sh \
+  | MEMRY_DOMAIN=memory.example.com bash
+```
+
+Set `MEMRY_API_KEY` to require `Authorization: Bearer <key>` on the API.
+
+### 4. CLI
+
+```bash
+memry add "I moved to Amsterdam and joined ASML" -u ada
+memry search "where does ada work" -u ada
+memry context "plan a commute" -u ada
+memry history <memory_id>          # full audit trail
+memry sweep                        # decay: soft-forget stale memories
+memry eval --dataset evals/datasets/synthetic_v1.jsonl
+```
+
+---
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[conversation] --> E[episodes<br/><i>immutable raw log</i>]
+    A --> X[extraction<br/><i>LLM distills facts</i>]
+    X --> R{reconcile}
+    R -- new --> ADD[ADD memory]
+    R -- overlaps --> UPD[UPDATE in place]
+    R -- contradicts --> SUP[invalidate old<br/>supersede with new]
+    R -- duplicate --> NONE[skip]
+    ADD & UPD & SUP --> M[(memories<br/>FTS5 + vectors + events)]
+    Q[agent query] --> H[hybrid retrieval<br/>RRF + recency + importance]
+    M --> H --> C[token-budgeted<br/>context block]
+```
+
+1. **Episodes first.** Every message is stored verbatim before anything is derived from it.
+   Memories are an index; episodes are the source of truth - you can re-run a better
+   extraction pipeline over them later.
+2. **Extraction** (Mem0-style phase 1): an LLM distills discrete, self-contained facts with
+   type (semantic / episodic / procedural), importance, categories, and entities. Without an
+   LLM, messages are stored verbatim so the system still works.
+3. **Reconciliation** (phase 2, with Zep-style temporal semantics): each fact is compared to
+   its most similar existing memories - duplicates are skipped, refinements rewrite in place,
+   and contradictions *invalidate* the old memory and link it to its successor.
+4. **Retrieval**: BM25 + cosine similarity fused with RRF, then boosted by recency
+   (half-life) and importance. Keyword-only when no embedder is configured.
+5. **Forgetting**: effective importance decays over time; `memry sweep` invalidates
+   memories that decayed below threshold.
+
+## Configuration
+
+Everything works with defaults. Override via env vars, `~/.memry/config.json`, or `Config(...)`:
+
+| Env var | Default | Notes |
+|---|---|---|
+| `MEMRY_DB_PATH` | `~/.memry/memry.db` | single SQLite file |
+| `MEMRY_BACKEND` | `local` | `local` \| `mem0` (needs `memry[mem0]`) |
+| `MEMRY_DEFAULT_USER` | `default` | user scope when the agent doesn't pass one |
+| `MEMRY_LLM_PROVIDER` | auto | `anthropic` \| `openai` \| `ollama` \| `none` - auto-detected from `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` |
+| `MEMRY_LLM_MODEL` | per provider | `claude-opus-4-8` / `gpt-5-mini` / `llama3.1` (use `claude-haiku-4-5` for a cheaper extraction model) |
+| `MEMRY_EMBEDDING_PROVIDER` | auto | `openai` \| `ollama` \| `voyage` \| `hash` \| `none` |
+| `MEMRY_API_KEY` | - | bearer token for the REST/MCP HTTP server |
+
+Anthropic extraction requires the optional SDK: `pip install "memry[anthropic]"`.
+
+## Evaluation
+
+```bash
+memry eval --dataset evals/datasets/synthetic_v1.jsonl -k 5
+```
+
+The harness ingests each case through the full write path, then scores retrieval
+(recall@k, MRR, latency p50/p95) - deterministic and offline, so it runs in CI. Format
+LoCoMo/LongMemEval into the same JSONL schema to compare providers, configs, and backends
+(including the Mem0 adapter) under identical conditions. See
+[docs/research/competitive-analysis.md](docs/research/competitive-analysis.md) for the
+landscape survey behind the design.
+
+## Project layout
+
+```
+src/memry/
+  models.py            # Episode / Memory / MemoryEvent (bi-temporal, provenance)
+  config.py            # env + file config, provider auto-detection
+  store.py             # MemoryStore - the public API
+  retrieval.py         # hybrid search: RRF + recency + importance
+  backends/            # storage interface, local SQLite engine, Mem0 adapter
+  intelligence/        # extraction, reconciliation, decay, context building
+  providers/           # LLMs (Anthropic/OpenAI/Ollama) & embeddings (+hash fallback)
+  mcp_server.py        # MCP tools (stdio + streamable HTTP)
+  rest.py              # REST API + dashboard + /mcp mount
+  evals/               # retrieval eval harness
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[Apache-2.0](LICENSE)

memry-0.2.0/README.md

@@ -0,0 +1,213 @@
+# Memry
+
+**[memry.tech](https://memry.tech)** - the open, self-hostable memory layer for AI agents. One `pip install`, zero services,
+plugged into any agent over MCP - with the intelligence layer (extraction, reconciliation,
+temporal invalidation, decay, context construction) as first-class, replaceable research code.
+
+```
+pip install memry
+memry mcp          # ← your agent now has long-term memory
+```
+
+- **MCP-native** - works with Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and any
+  other MCP client, over stdio or streamable HTTP.
+- **Local-first** - a single SQLite file. No vector DB, no Postgres, no cloud. Works with
+  **zero API keys** (FTS5 BM25 + deterministic hash embeddings), gets smarter the moment you
+  set `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`.
+- **Real memory, not a vector dump** - LLM extraction distills conversations into discrete
+  facts; reconciliation deduplicates, merges, and **supersedes contradicted memories instead
+  of deleting them** (bi-temporal: `valid_from` / `invalid_at` / `superseded_by`).
+- **Explainable retrieval** - hybrid vector + BM25 with reciprocal-rank fusion, boosted by
+  recency and importance; every result carries its score signals.
+- **Provenance & audit** - raw episodes are stored immutably; every memory links to its
+  source episodes; every mutation is an event you can inspect (`history`).
+- **Forgetting built in** - importance decays with a half-life; a decay sweep soft-forgets
+  stale trivia (invalidated, never destroyed).
+- **Entities, disambiguated** - mentions become first-class entities, and a name match is
+  never enough to merge: unclear cases stay separate ("three Jonases") with a merge
+  proposal you (or the system, once evidence is clear) confirm or reject later.
+- **Category filters** - `search(categories=["diet"])`, `memry search -c diet`,
+  `?categories=` on REST, `categories` on the MCP search tool.
+- **Scales when you need it** - optional usearch HNSW index (`memry[ann]`) for vector
+  search at scale, and a PostgreSQL + pgvector backend (`memry[postgres]`) for
+  multi-writer deployments. SQLite stays the zero-ops default.
+- **Multi-tenant ready** - per-tenant API keys with transparent namespacing and strict
+  isolation on the self-hosted server (`MEMRY_TENANTS`), plus an admin key.
+- **Research-grade** - a built-in eval harness (recall@k, MRR, latency) with a synthetic
+  dataset, plus a pluggable backend interface with an optional [Mem0](https://github.com/mem0ai/mem0)
+  adapter so you can benchmark against it under identical conditions.
+
+Apache-2.0. Your agents. Your memories. Your infrastructure.
+
+---
+
+## Quickstart
+
+### 1. As an MCP server (any agent)
+
+```jsonc
+// Claude Desktop / Cursor / Windsurf config
+{
+  "mcpServers": {
+    "memry": {
+      "command": "memry",
+      "args": ["mcp"],
+      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }   // optional but recommended
+    }
+  }
+}
+```
+
+```bash
+# Claude Code
+claude mcp add memry -- memry mcp
+```
+
+The server exposes: `save_memories`, `search_memories`, `get_memory_context`,
+`list_memories`, `update_memory`, `delete_memory`, `memory_history`, `memory_stats`.
+
+### 2. As a Python library
+
+```python
+from memry import MemoryStore
+
+store = MemoryStore()
+
+# write: extraction + reconciliation (or infer=False to store verbatim)
+store.add(
+    [{"role": "user", "content": "I'm Ada, a data engineer in Berlin. I prefer uv over pip."}],
+    user_id="ada",
+)
+
+# read: hybrid search with explainable scores
+for hit in store.search("what tooling does the user prefer?", user_id="ada"):
+    print(hit.score, hit.memory.content, hit.signals)
+
+# or a ready-to-inject, token-budgeted context block
+ctx = store.reconstruct_context("help me set up a new project", user_id="ada", token_budget=1200)
+print(ctx.text)
+```
+
+### 3. Self-hosted server (REST + dashboard + MCP)
+
+```bash
+memry serve --host 0.0.0.0 --port 8787
+# dashboard:  http://localhost:8787/
+# REST API:   http://localhost:8787/api/v1/...
+# MCP (HTTP): http://localhost:8787/mcp
+```
+
+Or with Docker:
+
+```bash
+docker compose up -d      # see docker-compose.yml
+```
+
+Or on a fresh VPS (Ubuntu/Debian) with automatic HTTPS - one command, any
+provider ([guide](docs/deploy-vps.md)):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/cosmin-novac/memry/main/deploy/install.sh \
+  | MEMRY_DOMAIN=memory.example.com bash
+```
+
+Set `MEMRY_API_KEY` to require `Authorization: Bearer <key>` on the API.
+
+### 4. CLI
+
+```bash
+memry add "I moved to Amsterdam and joined ASML" -u ada
+memry search "where does ada work" -u ada
+memry context "plan a commute" -u ada
+memry history <memory_id>          # full audit trail
+memry sweep                        # decay: soft-forget stale memories
+memry eval --dataset evals/datasets/synthetic_v1.jsonl
+```
+
+---
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[conversation] --> E[episodes<br/><i>immutable raw log</i>]
+    A --> X[extraction<br/><i>LLM distills facts</i>]
+    X --> R{reconcile}
+    R -- new --> ADD[ADD memory]
+    R -- overlaps --> UPD[UPDATE in place]
+    R -- contradicts --> SUP[invalidate old<br/>supersede with new]
+    R -- duplicate --> NONE[skip]
+    ADD & UPD & SUP --> M[(memories<br/>FTS5 + vectors + events)]
+    Q[agent query] --> H[hybrid retrieval<br/>RRF + recency + importance]
+    M --> H --> C[token-budgeted<br/>context block]
+```
+
+1. **Episodes first.** Every message is stored verbatim before anything is derived from it.
+   Memories are an index; episodes are the source of truth - you can re-run a better
+   extraction pipeline over them later.
+2. **Extraction** (Mem0-style phase 1): an LLM distills discrete, self-contained facts with
+   type (semantic / episodic / procedural), importance, categories, and entities. Without an
+   LLM, messages are stored verbatim so the system still works.
+3. **Reconciliation** (phase 2, with Zep-style temporal semantics): each fact is compared to
+   its most similar existing memories - duplicates are skipped, refinements rewrite in place,
+   and contradictions *invalidate* the old memory and link it to its successor.
+4. **Retrieval**: BM25 + cosine similarity fused with RRF, then boosted by recency
+   (half-life) and importance. Keyword-only when no embedder is configured.
+5. **Forgetting**: effective importance decays over time; `memry sweep` invalidates
+   memories that decayed below threshold.
+
+## Configuration
+
+Everything works with defaults. Override via env vars, `~/.memry/config.json`, or `Config(...)`:
+
+| Env var | Default | Notes |
+|---|---|---|
+| `MEMRY_DB_PATH` | `~/.memry/memry.db` | single SQLite file |
+| `MEMRY_BACKEND` | `local` | `local` \| `mem0` (needs `memry[mem0]`) |
+| `MEMRY_DEFAULT_USER` | `default` | user scope when the agent doesn't pass one |
+| `MEMRY_LLM_PROVIDER` | auto | `anthropic` \| `openai` \| `ollama` \| `none` - auto-detected from `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` |
+| `MEMRY_LLM_MODEL` | per provider | `claude-opus-4-8` / `gpt-5-mini` / `llama3.1` (use `claude-haiku-4-5` for a cheaper extraction model) |
+| `MEMRY_EMBEDDING_PROVIDER` | auto | `openai` \| `ollama` \| `voyage` \| `hash` \| `none` |
+| `MEMRY_API_KEY` | - | bearer token for the REST/MCP HTTP server |
+
+Anthropic extraction requires the optional SDK: `pip install "memry[anthropic]"`.
+
+## Evaluation
+
+```bash
+memry eval --dataset evals/datasets/synthetic_v1.jsonl -k 5
+```
+
+The harness ingests each case through the full write path, then scores retrieval
+(recall@k, MRR, latency p50/p95) - deterministic and offline, so it runs in CI. Format
+LoCoMo/LongMemEval into the same JSONL schema to compare providers, configs, and backends
+(including the Mem0 adapter) under identical conditions. See
+[docs/research/competitive-analysis.md](docs/research/competitive-analysis.md) for the
+landscape survey behind the design.
+
+## Project layout
+
+```
+src/memry/
+  models.py            # Episode / Memory / MemoryEvent (bi-temporal, provenance)
+  config.py            # env + file config, provider auto-detection
+  store.py             # MemoryStore - the public API
+  retrieval.py         # hybrid search: RRF + recency + importance
+  backends/            # storage interface, local SQLite engine, Mem0 adapter
+  intelligence/        # extraction, reconciliation, decay, context building
+  providers/           # LLMs (Anthropic/OpenAI/Ollama) & embeddings (+hash fallback)
+  mcp_server.py        # MCP tools (stdio + streamable HTTP)
+  rest.py              # REST API + dashboard + /mcp mount
+  evals/               # retrieval eval harness
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[Apache-2.0](LICENSE)