[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93325":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":12,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":14,"stars30d":14,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":15,"rankGlobal":8,"rankLanguage":8,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":17,"hasPages":17,"topics":19,"createdAt":8,"pushedAt":8,"updatedAt":20,"readmeContent":21,"aiSummary":22,"trendingCount":13,"starSnapshotCount":13,"syncStatus":23,"lastSyncTime":24,"discoverSource":25},93325,"HMS","Shadow-Weave\u002FHMS","Shadow-Weave",null,"Python",354,32,1,0,163,71.56,"MIT License",false,"main",[],"2026-07-22 04:02:08","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"docs\u002Fassets\u002Fbranding\u002Fhms-hero.png\" alt=\"Holographic Memory System\" width=\"94%\">\n\n### Structured Memory Intelligence for Reliable Long-Horizon Reasoning\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd valign=\"middle\">\u003Cstrong>ShadowWeave Team\u003C\u002Fstrong>\u003C\u002Ftd>\n    \u003Ctd width=\"74\" align=\"center\" valign=\"middle\">\n      \u003Cimg src=\"docs\u002Fassets\u002Fbranding\u002Fshadowweave-mark.png\" alt=\"ShadowWeave\" width=\"62\">\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\u003Ca href=\"https:\u002F\u002Farxiv.org\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FarXiv-coming_soon-B31B1B?style=flat-square&logo=arxiv&logoColor=white\" alt=\"arXiv: coming soon\">\u003C\u002Fa>\n\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-active-145DA0?style=flat-square\" alt=\"Project status: active\">\n\n[English](README.md) · [中文](README.zh-CN.md)\n\n\u003C\u002Fdiv>\n\n---\n\n## Abstract\n\nThe **Holographic Memory System (HMS)** is a reproducible long-term memory QA\nframework for studying whether structured answer-time evidence organization can\nimprove a language model's reasoning over retrieved memories.\n\nThe project focuses on the LongMemEval setting, where a question may require\nevidence from multiple sessions, timestamps, extracted memory facts, and raw\nsource snippets.\n\n## One-Command Automatic Memory\n\nHMS can wrap an existing OpenAI client so each model call automatically:\n\n```text\nuser input -> Recall relevant memories -> inject context -> call the LLM\n           -> Retain the completed user\u002Fassistant exchange\n```\n\nConfigure the model Base URL, API key, and model in `.env`, then run:\n\n```bash\nbash scripts\u002Frun_memory_demo.sh\n```\n\nThe script starts PostgreSQL and HMS locally, waits for the memory API, installs\nthe local SDK adapter in an isolated `uv` environment, and runs a two-turn demo.\nThe first turn stores a preference and project; the second turn recalls both\nwithout manually calling `retain()` or `recall()`.\n\nFor this demo, one `OPENAI_API_KEY` \u002F `OPENAI_BASE_URL` \u002F `OPENAI_MODEL` set is\nenough. The script reuses it for HMS reasoning and retain extraction when the\nrole-specific values remain unset. Set the embedding model separately when your\nprovider does not support `text-embedding-3-small`.\n\nThe application-side integration is one wrapper call:\n\n```python\nfrom openai import OpenAI\nfrom hms_litellm import wrap_openai\n\nclient = wrap_openai(\n    OpenAI(),\n    hms_api_url=\"http:\u002F\u002F127.0.0.1:18080\",\n    api_key=\"YOUR_HMS_API_KEY\",\n    bank_id=\"user-alice\",\n)\n\nresponse = client.responses.create(\n    model=\"gpt-4o-mini\",\n    input=\"What do you remember about my current project?\",\n)\n```\n\n`wrap_openai()` supports both `client.responses.create(...)` and\n`client.chat.completions.create(...)`, including streaming. Use a stable,\nper-user `bank_id`; optionally set `session_id` to accumulate one conversation\nas a tracked HMS document.\n\n## Experiment Design\n\nThe reproducible evaluation follows one complete pipeline:\n\n```text\nDataset conversations\n  -> Retain: extract and store structured memories\n  -> Recall: retrieve evidence for each question\n  -> Organize: build an answer-time evidence structure\n  -> Answer: generate a grounded response\n  -> Judge: compare the response with the gold answer\n```\n\nThe core idea is to avoid giving the answer model a loose list of retrieved\nfacts. Instead, the system builds an intermediate evidence structure that makes\ntime, source, event state, and numeric signals explicit before generation.\n\nThis setup is useful for studying questions such as:\n\n- whether the model can connect evidence across sessions\n- whether the model can distinguish old and current user states\n- whether the model can ground relative dates to concrete memories\n- whether the model can avoid duplicate counting\n- whether missing numeric sides are handled conservatively\n\n## Visual Demo\n\nThe project includes a database-free demo for external readers. It shows how\nraw retrieved sessions are converted into an organized evidence ledger before\nanswer generation.\n\n![Memory evidence organization demo](docs\u002Fassets\u002Fmemory_pipeline_demo.svg)\n\nOpen the standalone demo page:\n\n```text\ndocs\u002Fmemory_pipeline_demo.html\n```\n\nThis page can be viewed directly in a browser and does not require model keys,\ndatabase access, or benchmark artifacts.\n\n## Dynamic Case Replay\n\nThe repository also includes a concrete benchmark-style case replay. It shows a\nsingle multi-session question and animates how scattered session snippets move\nthrough retrieval, evidence ledger construction, deduplication, and grounded\nanswer generation.\n\n![Dynamic benchmark case replay](docs\u002Fassets\u002Fbenchmark_case_replay.svg)\n\nOpen the auto-playing replay page:\n\n```text\ndocs\u002Fbenchmark_case_replay.html\n```\n\nThe replay page auto-advances through the raw session snippets, recall candidates,\nledger rows, duplicate-control rule, answer packet, and final grounded response\nfor the same case.\n\n## Pipelines\n\nTwo pipeline modes are exposed through the benchmark script.\n\n### Ledger Pipeline\n\nThe ledger pipeline keeps memory retrieval unchanged and adds a structured\nevidence ledger before answer generation.\n\nFor high-risk question types, the ledger records:\n\n- event time\n- mention time\n- source session or document\n- fact type\n- compact evidence text\n- numeric, date, and update signals\n- raw source snippets for grounding\n\nUse this mode when you want to reproduce the main evidence-organization\nexperiment.\n\n### Self-Evolution Pipeline\n\nThe self-evolution pipeline keeps the ledger pipeline and adds a lightweight\nanswer-time controller. The controller is driven by diagnosed failure patterns:\n\n- count and total deduplication\n- relative-date lookup grounding\n- amount and difference calibration\n- current versus previous state arbitration\n\nThis mode is intended for studying whether targeted control instructions can\nimprove or change memory reasoning behavior after retrieval.\n\n## Repository Layout\n\n```text\n.\n├── .aaaSCRIPT\u002F\n│   └── run_benchmark.sh\n├── core\u002F\n│   ├── dataplane\u002F\n│   ├── daemon\u002F\n│   └── local-suite\u002F\n├── deploy\u002F\n├── docs\u002F\n│   ├── assets\u002F\n│   │   ├── branding\u002F\n│   │   │   ├── hms-banner.png\n│   │   │   ├── hms-hero.png\n│   │   │   ├── shadowweave-mark.png\n│   │   │   └── shadowweave_v6.png\n│   │   ├── benchmark_case_replay.svg\n│   │   └── memory_pipeline_demo.svg\n│   ├── benchmark_case_replay.html\n│   └── memory_pipeline_demo.html\n├── interface\u002F\n├── lab\u002F\n│   └── evaluation\u002F\n│       └── benchmarks\u002F\n│           ├── common\u002F\n│           │   └── benchmark_runner.py\n│           └── longmemeval\u002F\n│               └── longmemeval_benchmark.py\n├── tooling\u002F\n├── .env.example\n├── README.md\n└── README.zh-CN.md\n```\n\nImportant files:\n\n- `.aaaSCRIPT\u002Frun_benchmark.sh`: unified experiment script\n- `scripts\u002Frun_memory_demo.sh`: one-command automatic retain\u002Frecall demo\n- `examples\u002Fautomatic_memory\u002Fopenai_responses.py`: two-turn OpenAI Responses API example\n- `docs\u002Fassets\u002Fbranding\u002Fhms-banner.png`: project identity banner\n- `docs\u002Fassets\u002Fbranding\u002Fhms-hero.png`: compact README project header\n- `docs\u002Fassets\u002Fbranding\u002Fshadowweave-mark.png`: compact ShadowWeave team mark\n- `docs\u002Fassets\u002Fbranding\u002Fshadowweave_v6.png`: ShadowWeave team identity artwork\n- `docs\u002Fbenchmark_case_replay.html`: auto-playing single-case process replay\n- `docs\u002Fassets\u002Fbenchmark_case_replay.svg`: README-embedded animated case replay\n- `docs\u002Fmemory_pipeline_demo.html`: static before\u002Fafter visualization\n- `docs\u002Fassets\u002Fmemory_pipeline_demo.svg`: README-embedded visual summary\n- `lab\u002Fevaluation\u002Fbenchmarks\u002Flongmemeval\u002Flongmemeval_benchmark.py`: LongMemEval pipeline implementation\n- `lab\u002Fevaluation\u002Fbenchmarks\u002Fcommon\u002Fbenchmark_runner.py`: shared evaluation runner\n- `.env.example`: local configuration template\n\n## Environment Setup\n\nCreate a local environment file:\n\n```bash\ncp .env.example .env\n```\n\nOpen `.env` and replace the `*_change_me` values. The main model settings are:\n\n| Pipeline role | Base URL | API key | Model |\n| --- | --- | --- | --- |\n| Core HMS \u002F recall organization | `HMS_API_LLM_BASE_URL` | `HMS_API_LLM_API_KEY` | `HMS_API_LLM_MODEL` |\n| Retain \u002F fact extraction | `HMS_API_RETAIN_LLM_BASE_URL` | `HMS_API_RETAIN_LLM_API_KEY` | `HMS_API_RETAIN_LLM_MODEL` |\n| Answer generation | `HMS_API_ANSWER_LLM_BASE_URL` | `HMS_API_ANSWER_LLM_API_KEY` | `HMS_API_ANSWER_LLM_MODEL` |\n| LLM judge | `HMS_API_JUDGE_LLM_BASE_URL` | `HMS_API_JUDGE_LLM_API_KEY` | `HMS_API_JUDGE_LLM_MODEL` |\n| Embeddings | `HMS_API_EMBEDDINGS_OPENAI_BASE_URL` | `HMS_API_EMBEDDINGS_OPENAI_API_KEY` | `HMS_API_EMBEDDINGS_OPENAI_MODEL` |\n\nAll roles may point to the same OpenAI-compatible service. In that case, use\nthe same Base URL and API key in each section while choosing models appropriate\nfor each role. Also configure:\n\n- `HMS_API_DATABASE_URL`: a reachable PostgreSQL database with `pgvector`\n- `HMS_DATASET_PATH`: the local LongMemEval dataset JSON path\n- `HMS_PIPELINE`: `ledger` or `self_evolution`\n\nThe framework loads configuration from `.env`. Do not hard-code credentials in\nthe source code, and never commit the populated `.env` file.\n\n## Reproduction Logic\n\nThe benchmark script now defaults to the full clean reproduction path:\n\n```text\nRetain -> Recall -> Answer -> Judge\n```\n\nFor every benchmark item, HMS first retains the conversation sessions, recalls\nrelevant memories for each question, generates a grounded answer, and finally\nuses the configured judge model to score that answer against the gold answer.\n\nRecommended first run:\n\n```text\n1. Copy .env.example to .env\n2. Fill database, Base URL, API key, model, and dataset settings\n3. Start with one or two benchmark instances\n4. Verify Retain, Recall, Answer, and Judge all complete\n5. Increase concurrency and benchmark size\n6. Inspect results under .aaaRESULT\u002F and logs under .aaaLOG\u002F\n```\n\nUse `HMS_RETRIEVAL_ONLY=1` only for a later iteration when the same memories are\nalready present in the database and you intentionally want to rerun only\nRecall → Answer → Judge.\n\n## Minimal End-to-End Run\n\n```bash\ncp .env.example .env\n# Edit .env before continuing.\n\nexport HMS_BENCHMARK=longmemeval\nexport HMS_PIPELINE=ledger\nexport HMS_RETRIEVAL_ONLY=0\nexport HMS_MAX_INSTANCES=2\n\nbash .aaaSCRIPT\u002Frun_benchmark.sh \\\n  --parallel 1 \\\n  --max-concurrent-questions 1 \\\n  --eval-semaphore-size 1\n```\n\nThe script prints the active mode at startup. For a clean reproduction it must\nprint `HMS reproduction mode: Retain -> Recall -> Judge`.\n\n## Run the Ledger Pipeline\n\n```bash\nexport HMS_RETRIEVAL_ONLY=0\nexport HMS_PIPELINE=ledger\nexport HMS_MAX_INSTANCES=500\nexport HMS_SESSION_EXPANSION_WEIGHT=0.5\n\nbash .aaaSCRIPT\u002Frun_benchmark.sh \\\n  --parallel 8 \\\n  --max-concurrent-questions 8 \\\n  --eval-semaphore-size 8 \\\n  --quiet\n```\n\n## Run the Self-Evolution Pipeline\n\n```bash\nexport HMS_RETRIEVAL_ONLY=0\nexport HMS_PIPELINE=self_evolution\nexport HMS_MAX_INSTANCES=500\nexport HMS_SESSION_EXPANSION_WEIGHT=0.5\n\nbash .aaaSCRIPT\u002Frun_benchmark.sh \\\n  --parallel 8 \\\n  --max-concurrent-questions 8 \\\n  --eval-semaphore-size 8 \\\n  --quiet\n```\n\n## Common Runtime Options\n\nUseful environment variables:\n\n- `HMS_PIPELINE`: `ledger` or `self_evolution`\n- `HMS_RETRIEVAL_ONLY`: defaults to `0`; set to `1` only to reuse retained memories\n- `HMS_MAX_INSTANCES`: limit the number of evaluated questions\n- `HMS_MAX_QUESTIONS`: limit questions after filtering\n- `HMS_DATASET_PATH`: provide a local LongMemEval dataset path\n- `HMS_SESSION_EXPANSION_WEIGHT`: override session expansion weight\n- `HMS_PYTHON_BIN`: use a specific Python interpreter\n\nUseful command-line options:\n\n- `--parallel`: number of instances processed concurrently\n- `--max-concurrent-questions`: maximum concurrent question-level tasks\n- `--eval-semaphore-size`: evaluator concurrency limit\n- `--category`: run a specific LongMemEval category\n- `--question-id`: run one or more question IDs\n- `--skip-ingestion`: skip ingestion and use existing database memories\n- `--quiet`: reduce console output\n\n## Runtime Artifacts\n\nWhen the experiment runs, local runtime artifacts are written under ignored\ndirectories:\n\n```text\n.aaaLOG\u002F\n.aaaRESULT\u002F\n```\n\nThese directories are for local reproduction and should not be committed.\n","Holographic Memory System（HMS）是一个面向长周期推理的结构化长期记忆问答框架，旨在通过组织化存储与检索多会话、带时间戳的记忆事实及原始片段，提升大语言模型在跨轮次复杂问答中的推理可靠性。其核心功能包括自动化的记忆存取闭环（输入→召回→注入→生成→留存）、支持 PostgreSQL 的结构化记忆银行、轻量级 OpenAI 客户端封装接口，以及可复现的 LongMemEval 评估流水线。适用于需持续记忆用户偏好、项目上下文或跨对话状态维护的智能体应用，如个性化助手、企业知识协作者或教育对话系统。",2,"2026-07-16 02:30:07","CREATED_QUERY"]