spomory 0.1.0__tar.gz

spomory-0.1.0/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"3d509812-ea3e-4078-9b6d-fa66ce821bd8","pid":15034,"procStart":"Sat Sep  5 10:23:25 2026","acquiredAt":1788679152497}

spomory-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --python 3.11
+
+      - name: Lint (ruff)
+        run: uv run --python 3.11 ruff check .
+
+      - name: Test (pytest)
+        run: uv run --python 3.11 pytest

spomory-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.db
+*.sqlite3
+.DS_Store
+benchmarks/results/*.json
+!benchmarks/results/.gitkeep
+!benchmarks/results/locomo_subset_smoke.json
+!benchmarks/results/locomo_subset_baseline.json
+!benchmarks/results/locomo_full_run.json
+!benchmarks/results/locomo_full_run_after_date_fix.json
+!benchmarks/results/multimodal_eval.json
+!benchmarks/results/multimodal_real_extraction.json
+benchmarks/data/*
+!benchmarks/data/images
+!benchmarks/data/images/*.jpg
+!benchmarks/data/multimodal_ground_truth.json
+
+# internal working docs, not for the public repo
+TASKS.md
+AI个人记忆方案.docx
+AI个人记忆方案-v2.docx
+运维.md
+PH.md
+GOAL.md
+GOALs.md
+VIDEO_SCRIPT.md

spomory-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

spomory-0.1.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.5
+Name: spomory
+Version: 0.1.0
+Summary: Persistent memory for AI agents via MCP — entity/relation knowledge graph, HippoRAG-style retrieval, local-first
+Project-URL: Homepage, https://spomory.yliuai.com
+Project-URL: Repository, https://github.com/yliuai/spomory
+Project-URL: Documentation, https://github.com/yliuai/spomory/blob/main/docs/mcp_quickstart.en.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.0
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: embedding
+Requires-Dist: sentence-transformers>=3.0; extra == 'embedding'
+Provides-Extra: llm
+Requires-Dist: openai>=1.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0; extra == 'mcp'
+Provides-Extra: multimodal
+Requires-Dist: pillow>=10.0; extra == 'multimodal'
+Requires-Dist: torch>=2.0; extra == 'multimodal'
+Requires-Dist: transformers>=4.40; extra == 'multimodal'
+Provides-Extra: rl
+Requires-Dist: peft>=0.11; extra == 'rl'
+Requires-Dist: transformers>=4.40; extra == 'rl'
+Requires-Dist: trl>=0.9; extra == 'rl'
+Description-Content-Type: text/markdown
+
+# Spomory
+
+**English | [中文](README.zh-CN.md)**
+
+The core engine behind a personal AI memory product: HippoRAG-style
+retrieval (query→triple matching + personalized PageRank diffusion) +
+a LightRAG-style dual-layer incremental knowledge graph + a lightweight
+GRPO-trained memory-management policy, exposed to Claude Desktop / Cursor
+and other clients via an MCP server, with a path to a cloud deployment
+(Postgres backend, FastAPI auth/billing skeleton) already scaffolded.
+
+> Spomory is the product/client-facing display name. The Python package
+> name, CLI command (`memory-core-mcp`), and module name (`memory_core`)
+> are unchanged — see the "Quickstart: MCP Server" section below.
+
+## What's implemented
+
+- **Pluggable LLM / embedding providers**: defaults to any OpenAI-compatible
+  API (including Chinese-market LLM providers) + local
+  `sentence-transformers` (default `bge-m3`, bilingual Chinese/English).
+- **Dual-layer incremental knowledge graph**: entities and relations are
+  modeled as independent layers; new data is only extracted and merged in,
+  never a full rebuild. Exact-match filler input ("thanks", "好的", "ok", ...)
+  is skipped before it ever reaches the extraction LLM call, since it can't
+  contain an extractable fact — relevant cost protection on any
+  unauthenticated endpoint. Defaults to a local `LocalGraphStore`
+  (networkx + SQLite); a `PostgresGraphStore` cloud implementation also
+  exists, and both share the same behavioral contract test suite.
+- **HippoRAG 2-style retrieval**: the query is matched directly against
+  triples rather than only against entity nodes; the matched seed nodes
+  are diffused via personalized PageRank for multi-hop association, then
+  assembled into a natural-language context (with source timestamps, so
+  "when did I mention X" is answerable). Ranking on top of that decays a
+  relation's relevance the longer it's gone without being retrieved, and
+  boosts it back up (log-dampened, so it can't dominate PPR rank) the more
+  times the same fact has been restated — a passive signal alongside the
+  active ADD/UPDATE/DELETE/NOOP decisions below.
+- **Memory management**: an ADD/UPDATE/DELETE/NOOP action space, with a
+  rule-based default policy (`RuleBasedPolicy`) and a full GRPO training
+  pipeline (`memory_manager/train_grpo.py`, actually run and verified on
+  a real GPU).
+- **MCP Server**: exposes six tools — `add_memory`, `search_memory`,
+  `get_graph`, `export_memory`, `forget_memory`, `forget_all_memory` —
+  verified end-to-end against a real Claude Desktop.
+- **Memory passport export + true delete**: a JSON-LD style export format,
+  physical deletion, and an audit log.
+- **Multimodal image verification**: image captioning → reuses the text
+  extraction pipeline → CLIP cross-checks candidate triples. Honestly
+  positioned as "verification," not "native cross-modal extraction."
+- **Cloud skeleton**: FastAPI user auth/API keys/quotas, a Stripe webhook
+  billing scaffold (skeleton-level only, not production-deployed).
+
+## Project layout
+
+```
+src/
+├── memory_core/
+│   ├── graph/            # entity/relation models, storage adapters (local SQLite / cloud Postgres), incremental writes
+│   ├── retrieval/        # query→triple matching, personalized PageRank, context assembly
+│   ├── memory_manager/   # action space, reward functions, GRPO training script, policy inference
+│   ├── multimodal/       # image captioning + CLIP verification
+│   ├── mcp_server/       # MCP Server (the distribution entry point)
+│   ├── export/           # memory passport export format + true delete
+│   ├── llm/              # pluggable LLM/embedding providers
+│   ├── audit.py          # deletion audit log
+│   └── usage.py          # retention/usage tracking
+└── cloud_api/            # FastAPI cloud service skeleton (auth, quotas, billing)
+benchmarks/                # LoCoMo/LongMemEval evaluation harness + multimodal comparison experiments
+tests/                     # 94+ tests, from unit tests to real LLM/GPU/Postgres end-to-end verification
+docs/                      # per-epic design notes, verification reports, runbooks (see index below)
+```
+
+## Installation
+
+Prerequisites: Python **3.11+**, [uv](https://docs.astral.sh/uv/getting-started/installation/)
+(no uv? `python -m venv` + `pip install -e` works as a substitute for the
+`uv` commands below).
+
+```bash
+git clone <this repo's URL> memory-core && cd memory-core
+uv venv --python 3.11 .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+
+# Pick dependency groups as needed — they can be combined, no need to install everything:
+uv pip install -e ".[dev]"                 # required to run tests/lint
+uv pip install -e ".[llm,embedding]"       # required for the "minimal working memory system" (see the demo below)
+uv pip install -e ".[mcp]"                 # extra: connecting to Claude Desktop/Cursor
+uv pip install -e ".[rl]"                  # extra: GRPO training (requires a GPU + CUDA)
+uv pip install -e ".[cloud]"               # extra: cloud API / Postgres backend
+uv pip install -e ".[multimodal]"          # extra: image + CLIP verification
+```
+
+The `embedding` group downloads the default model `BAAI/bge-m3` from
+HuggingFace on first use (~2.2GB) — make sure huggingface.co is reachable
+(if you're behind the Great Firewall, `export HF_ENDPOINT=https://hf-mirror.com`
+routes through a mirror). You can also swap in a smaller model via
+`export EMBEDDING_MODEL=<any sentence-transformers model name>`.
+
+The `llm` group itself downloads nothing, but **`LLM_API_KEY` must be set
+at runtime** (any OpenAI-compatible Chat Completions endpoint works — OpenAI,
+DeepSeek, Qwen, etc.):
+
+```bash
+export LLM_API_KEY=sk-...
+export LLM_BASE_URL=https://api.deepseek.com   # optional; defaults to OpenAI's endpoint
+export LLM_MODEL=deepseek-chat                 # optional; defaults to gpt-4o-mini
+```
+
+### Run a minimal example (no MCP, plain Python calls)
+
+With `dev` + `llm` + `embedding` installed and the three env vars above
+set, this script exercises the full "write a memory → retrieve it"
+pipeline directly (the same logic behind `mcp_server/server.py`'s
+`add_memory`/`search_memory` tools, just calling the library directly
+instead of going through the MCP protocol layer):
+
+```python
+# demo.py
+from memory_core.graph.local_store import LocalGraphStore
+from memory_core.graph.incremental import IncrementalIngestor
+from memory_core.llm.openai_compatible import OpenAICompatibleProvider
+from memory_core.llm.local_sentence_transformer import SentenceTransformerProvider
+from memory_core.memory_manager.policy import RuleBasedPolicy
+from memory_core.retrieval.ppr import personalized_pagerank, rank_entities
+from memory_core.retrieval.query_match import match_query_to_triples
+from memory_core.retrieval.ranker import build_context
+
+store = LocalGraphStore("demo.sqlite3")          # a local file; delete it to reset
+llm = OpenAICompatibleProvider()                 # reads LLM_API_KEY etc. from the environment
+embedder = SentenceTransformerProvider()         # downloads bge-m3 on first run
+
+# 1. Write a memory: the LLM extracts triples, incrementally merged into the graph
+ingestor = IncrementalIngestor(store, llm, policy=RuleBasedPolicy())
+result = ingestor.ingest("I do AI research at CAS, mostly in Python.", source_id="demo")
+print(f"added {result.new_entities} entities, {result.new_relations} relations")
+
+# 2. Retrieve: match the query against triples -> PPR diffusion -> assemble a natural-language context
+query = "Where do I work?"
+entities, relations = store.all_entities(), store.all_relations()
+entities_by_id = {e.id: e for e in entities}
+matches = match_query_to_triples(query, relations, entities_by_id, embedder, top_k=10)
+seed_ids = {r.relation.subject_id for r in matches} | {r.relation.object_id for r in matches}
+scores = personalized_pagerank(entities, relations, seed_entity_ids=list(seed_ids))
+ranked_ids = [eid for eid, _ in rank_entities(scores)]
+print(build_context(relations, entities_by_id, ranked_ids, top_k=10))
+```
+
+```bash
+python demo.py
+```
+
+Here's real output from a live run against DeepSeek with the exact input
+shown above (not fabricated, not cleaned up — this is what actually came
+back):
+
+```
+added 3 entities, 2 relations
+I do AI research at CAS (recorded at 2026-09-05 10:40:00).I do AI research mostly in Python (recorded at 2026-09-05 10:40:00).
+```
+
+Exact wording and entity/relation counts depend on the LLM's own
+extraction and will vary between runs, but as long as the env vars are
+set correctly, non-empty output means the pipeline works end to end.
+`retrieval/ranker.py` detects whether a relation's text is CJK or not and
+renders it accordingly (no spaces + a Chinese timestamp label for CJK,
+spaced words + an English timestamp label otherwise), so English input no
+longer comes out as one run-on word like earlier versions of this demo
+did.
+
+## Quickstart: MCP Server (connecting to Claude Desktop / Cursor / Codex CLI)
+
+This MCP server shows up in Claude Desktop / Cursor / Codex CLI as **Spomory** (set
+by the `mcpServers` key in the client's config file — see the docs
+below). The Python package name and CLI command are still
+`memory-core` / `memory-core-mcp`; the two are independent of each other.
+
+With the `mcp` dependency group installed and `LLM_API_KEY` etc. set:
+
+```bash
+uv pip install -e ".[llm,embedding,mcp]"
+memory-core-mcp   # stays running as a stdio MCP server, waiting for a client to connect
+```
+
+Data lives in `~/.memory-core/` by default (override with
+`MEMORY_CORE_DATA_DIR`); setting `DATABASE_URL` switches to the Postgres
+backend instead of local SQLite.
+
+Connecting it to Claude Desktop / Cursor / Codex CLI requires registering
+this command's **absolute path** in the client's config file (don't rely
+on `PATH`). Full steps, a config file example, and a real gotcha we
+actually hit (macOS's TCC privacy protection blocks a venv running under
+`~/Documents`) are in
+[`docs/mcp_quickstart.en.md`](docs/mcp_quickstart.en.md).
+
+## Measured results
+
+Real runs against DeepSeek on 84 QA pairs from LoCoMo-10 (conv-26, first
+150 turns) — not cherry-picked, and not competitive with the bigger
+players' published numbers yet:
+
+| Metric | Value |
+|---|---|
+| Recall@10 (did the right evidence turn make it into context) | 52.4% |
+| Accuracy — strict substring match | 19.0% |
+| Accuracy — LLM-judged (looser, wording-tolerant) | 44.0% |
+
+A prior run (before a fix that folds dates into extracted predicates so
+"when" questions are answerable) scored lower on accuracy but higher on
+recall (62.0%) — the fix traded some retrieval recall for a real
++14.3-point accuracy gain, and we went and found out exactly why instead
+of just reporting the accuracy number: the date-folding instruction
+sometimes misfires on content-free small talk ("Thanks!" → "thanked on
+2023-07-03"), and those extra low-value triples crowd out relevant ones
+out of the fixed top-10 retrieval window. Full numbers, per-category
+breakdown, and the side-by-side extraction comparison that found this are
+in [`docs/benchmark_smoke_test.md`](docs/benchmark_smoke_test.md).
+
+**LongMemEval** (`xiaowu0162/longmemeval-cleaned` oracle variant, first 10
+of 500 questions):
+
+| Metric | Value |
+|---|---|
+| Recall@10 | 100% (10/10) |
+| Accuracy — strict substring match | 30% |
+| Accuracy — LLM-judged | 80% |
+
+The limitations here matter as much as the numbers:
+1. **Only 10 questions, not the full 500** — each question ingests ~27
+   turns on average (~27 real extraction calls plus one generation and one
+   judge call), and this environment's LLM API calls go through a proxy
+   with real latency; the full dataset would take tens of hours. This is a
+   real run, not a mock, but it's a small sample and shouldn't be read as
+   generalizing to the full dataset.
+2. **All 10 happen to be `temporal-reasoning` type** — the dataset also has
+   a `multi-session` type; `load_longmemeval(limit=10)` takes the first 10
+   entries in file order with no stratified sampling, so this sample isn't
+   representative of the dataset as a whole.
+3. **Recall@10 = 100% is largely an artifact of the oracle variant's
+   design, not a strong retrieval claim** — the oracle variant pre-filters
+   each question's haystack down to only the relevant sessions (no
+   distractor sessions), which is considerably easier than a real
+   deployment's memory store (hundreds/thousands of unrelated turns). This
+   isn't the same task as the full (non-oracle) LongMemEval benchmark and
+   shouldn't be compared directly against numbers other products report on
+   that harder variant.
+4. Strict-match accuracy (30%) is far below LLM-judged accuracy (80%),
+   consistent with the same pattern seen in the LoCoMo results — substring
+   matching systematically undercounts answers that are correct but worded
+   differently.
+
+Raw data:
+[`benchmarks/results/longmemeval_oracle_subset.json`](benchmarks/results/longmemeval_oracle_subset.json);
+the run script is
+[`benchmarks/run_longmemeval_subset.py`](benchmarks/run_longmemeval_subset.py).
+
+## Testing
+
+```bash
+pytest                    # everything
+pytest -m "not slow"      # skip tests that download models / train — runs in seconds
+```
+
+Most of the "slow" tests aren't mocked — they're real calls (real LLM API,
+real local embedding model, real CLIP model) and need the corresponding
+env vars (`LLM_API_KEY`, etc.) or an already-downloaded model cache.
+
+## Documentation index
+
+| Doc | Content |
+|---|---|
+| [mcp_quickstart.en.md](docs/mcp_quickstart.en.md) ([中文](docs/mcp_quickstart.md)) | MCP Server install, configuration, connecting Claude Desktop/Cursor/Codex CLI, real-world gotchas |
+| [graph_store_interface.en.md](docs/graph_store_interface.en.md) ([中文](docs/graph_store_interface.md)) | Storage adapter interface design |
+| [export_format.en.md](docs/export_format.en.md) ([中文](docs/export_format.md)) | The "memory passport" export format |
+| [dataset_format.en.md](docs/dataset_format.en.md) ([中文](docs/dataset_format.md)) | GRPO training data format and how the real dataset was generated |
+| [methodology.en.md](docs/methodology.en.md) ([中文](docs/methodology.md)) | Technical methodology: what's actually verified vs. still open |
+| [benchmark_smoke_test.en.md](docs/benchmark_smoke_test.en.md) ([中文](docs/benchmark_smoke_test.md)) | Real LoCoMo benchmark results and failure-case analysis |
+| [memory_manager_eval.en.md](docs/memory_manager_eval.en.md) ([中文](docs/memory_manager_eval.md)) | Rule-based vs. GRPO-trained policy comparison, including the debugging process |
+| [multimodal_verification.en.md](docs/multimodal_verification.en.md) ([中文](docs/multimodal_verification.md)) | Image + CLIP verification experiment results |
+| [gpu_training_runbook.en.md](docs/gpu_training_runbook.en.md) ([中文](docs/gpu_training_runbook.md)) | GPU training environment setup log (including real gotchas hit) |
+| [postgres_setup.en.md](docs/postgres_setup.en.md) ([中文](docs/postgres_setup.md)) | Cloud Postgres backend deployment log |
+| [leaderboard_submission.en.md](docs/leaderboard_submission.en.md) ([中文](docs/leaderboard_submission.md)) | Third-party leaderboard research |
+| [mvp_scope.en.md](docs/mvp_scope.en.md) ([中文](docs/mvp_scope.md)) | MVP scope definition |
+| [privacy_policy_draft.en.md](docs/privacy_policy_draft.en.md) ([中文](docs/privacy_policy_draft.md)) / [product_copy_memory_passport.en.md](docs/product_copy_memory_passport.en.md) ([中文](docs/product_copy_memory_passport.md)) | Draft privacy policy / external-facing product copy |
+| [eng_note_cjk_rendering_bug.en.md](docs/eng_note_cjk_rendering_bug.en.md) ([中文](docs/eng_note_cjk_rendering_bug.md)) | Engineering note: a real discover→fix→verify trace for a CJK rendering bug |
+
+Every doc above now has both a Chinese and an English version.
+
+## Known limitations
+
+- Multimodal verification for voice input (ASR + audio embedding) isn't
+  implemented yet.
+- The GRPO training dataset (140 real samples) and the number of training
+  steps are still small; `memory_manager_eval.md` honestly documents how
+  that limits training effectiveness.
+- The cloud API/billing is skeleton-level only and hasn't been connected
+  to a real production environment.
+
+## License
+
+See [LICENSE](LICENSE).