hyatlas-memory 1.0.0__tar.gz

hyatlas_memory-1.0.0/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+> All notable changes to HyAtlas-Memory are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-19
+
+### Added
+- **First stable release.** PyPI package `hyatlas-memory` installable via `pip install hyatlas-memory`.
+- `__all__` exports in `hyatlas_memory` (`HyMemoryProvider`, `__version__`).
+- `MANIFEST.in` ensures LICENSE, README, CHANGELOG, CONTRIBUTING, docs/, and tests ship in the sdist.
+- `hyatlas` console_scripts entry point — `pip install -e .` then `hyatlas start|--stop|--status` works from any directory.
+- `docker-compose.yml` — one-command full stack via `docker-compose up -d`.
+- `Dockerfile` (python:3.11-slim) and `.dockerignore`.
+- Token-based dashboard auth when bound to `0.0.0.0` (auto-generated 32-char token, stored at `~/.hy_memory/.dashboard_token`, cookie-based session, `/api/health` exempt).
+- `hyatlas_memory.start` module wrapping `start.py` for the entry point.
+- **Experimental layer-as-importance scoring** (on by default, set `HYATLAS_MEMORY_IMPORTANCE=0` to disable).
+  Upstream `hy-memory` ships a 4-factor `MemoryScorer`
+  (semantic 0.50 + recency 0.30 + importance 0.15 + access 0.05). The
+  `importance` and `access` inputs were never populated by the SDK, so the
+  0.15 and 0.05 terms effectively stayed zero. HyAtlas now writes a layer-derived
+  `importance` score (l4_identity=1.0, l2_fact=0.8, l3_summary=0.6,
+  l0_basic_info=0.5, l1_raw=0.3) on each new memory, restoring the full scorer.
+  No LLM cost.
+- **Access-count tracking** (on by default, set `HYATLAS_MEMORY_ACCESS_COUNT=0` to disable).
+  Increments `access_count` on every memory returned by a recall operation, so
+  the upstream `MemoryScorer` has a live access signal. Runs in a
+  fire-and-forget thread so it never blocks recall.
+- Integration tests in `tests/test_integration.py` covering the full local stack: Qdrant + upstream hy-memory server + `HyMemoryProvider`. Backfilled by default-on importance/access-count tracking.
+- `unit` and `integration` pytest markers so CI can run the fast suite without the live stack.
+- Dashboard front-end refactor: split the monolithic `app.js` into `app.js`, `js/l5.js`, and `js/observatory.js` to isolate the L5 knowledge graph and Three.js observatory modules; `server/dashboard/dashboard.py` now serves files under `/js/`.
+
+### Changed
+- **Qdrant auto-detection** — removes hardcoded `C:\qdrant\qdrant.exe`; auto-detects via `QDRANT_BIN` env var → `PATH` → common OS locations. Skips launch if already running (Docker).
+- `pyproject.toml` — `[project.scripts]`, per-file ruff ignores, `long_description_content_type` is now auto-detected from `README.md`.
+- README — Quick Start moved above How It Works; prerequisites table added; `hyatlas` CLI command documented; runtime vs dev install separated.
+
+### Fixed
+- `start.py` path resolution broken when invoked via console_scripts (double dirname on `src/` layout).
+- README forcing dev/test deps on normal users (cleanly separated runtime vs dev).
+- Missing `__main__` guard in entry wrapper.
+- Startup script argv not forwarded (documented).
+
+## [0.6.0] - 2026-06-18
+
+### Added
+- `start.py` — one-command startup for the full stack (Qdrant → upstream → dashboard)
+- Sequential health checks between each service start
+- Auto-cleanup of stale processes on occupied ports
+- `--stop` and `--status` commands for service management
+- Live status terminal pinned to taskbar (Windows `CREATE_NEW_CONSOLE`)
+- Emoji status header (🧠 Hy-Memory, 📊 Dashboard, 🗄️ Qdrant)
+- Service logs written to `logs/` directory
+- Graceful Ctrl+C shutdown (kills all child processes in reverse order)
+- Crash recovery — auto-restarts a service if it dies during health-check window
+- `CREATE_NO_WINDOW` flag suppresses blank console popups from child processes
+
+## [0.5.0] - 2026-06-18
+
+### Added
+- Full documentation suite: `docs/DASHBOARD.md`, `docs/API.md`, `docs/LAYERS.md`, `docs/TROUBLESHOOTING.md`
+- `CONTRIBUTING.md` — contributor guidelines
+- `CHANGELOG.md` — this file
+- Social preview images for the GitHub repo
+
+### Changed
+- README updated with documentation links and dashboard quick start
+
+## [0.4.0] - 2026-06-18
+
+### Added
+- Memory Observatory: 3D galaxy visualization with 8 memory layers
+- Observatory entrance animation (nodes fly from center on first load)
+- Observatory scope-change morph animation (cubic ease between zoom levels)
+- Cross-layer edge rendering with warm-gold color + higher opacity
+- Density-based opacity scaling for crowded layers
+- Initial boot screen with HyAtlas logo + progress bar
+- Smooth page transitions (fade + slide) on navigation
+- Galaxy seed loading animation (covers only main content area)
+- HyAtlas branding (proper case "HyAtlas" replaces "HY-MEMORY" / "HYATLAS")
+
+### Changed
+- Default Observatory load state: ALL layers + Last 500 scope
+- Legend bar moved outside the 3D canvas
+- `computeObservatoryEdges` rewritten for guaranteed cross-layer connections
+- `computeObservatoryFitZoom` rewritten with proper geometry math
+
+### Fixed
+- Camera clipping at far plane (increased from 2000 to 8000)
+- Galaxy oversized at large scopes (0.45x scaling for scope > 100)
+- Stale dashboard process cleanup on startup
+
+## [0.3.0] - 2026-06-18
+
+### Fixed
+- Re-entrant lock deadlock in `sync_turn` (`threading.Lock` → `threading.RLock`)
+- 5-bug chain causing silent cross-session memory write failures
+- `_persist_buffer_to_disk` re-entering the same lock it was already holding
+- `register_memory_tool` crash on `ToolRegistry` with no such method
+- Qdrant storage path mismatch after PC restart (`--config-path` requirement)
+
+## [0.2.0] - 2026-06-16
+
+### Added
+- System2 writer with scheduled trigger mode
+- Kuzu graph store for L5 knowledge, L6 schema, L7 intention layers
+- Cross-encoder reranking for recall quality
+- L5 pipeline: 7-step graph rebuild batch job
+
+## [0.1.0] - 2026-06-15
+
+### Added
+- Initial release
+- 7-layer memory model (L0 basic info → L7 intention)
+- Hermes Agent plugin via `MemoryProvider` interface
+- Local HTTP dashboard on port 8765
+- Local upstream server on port 19527
+- 9 carried SDK patches (LLMConfig env-loading, cross-encoder rerank, etc.)
+- 4-tier context pressure monitor (fastpath → emergency)
+- `hermes hy-memory` CLI subcommands: `doctor`, `add`, `search`, `list`, `init`, `install`, `reset`
+- Coding memory subsystem (sqlite-backed)
+- 12-test pytest suite
+
+### Known limitations
+- `dashboard.html` is a single 3,200-line file
+- No auth on the dashboard (loopback only by design)
+- No docker-compose for the full stack
+- L7 intention layer is experimental, not part of the official Hy-Memory spec
+
+---
+
+## Versioning policy
+
+- **Major (X.0.0)** — breaking changes to the public API (plugin interface, dashboard HTTP API, or data formats)
+- **Minor (0.X.0)** — new features, non-breaking. Layer additions, new CLI subcommands, new dashboard pages
+- **Patch (0.0.X)** — bug fixes, performance improvements, docs
+
+## Release cadence
+
+There is no fixed release schedule. Releases are cut when:
+1. A meaningful chunk of work has accumulated (5+ merged PRs, or a major feature)
+2. A critical bug fix needs to be pushed
+3. The maintainer feels like it
+
+The current maintainer is [@tuancookiez-hub](https://github.com/tuancookiez-hub). If you're a regular contributor and want release-cutter permissions, ask.
+
+## Migration guides
+
+When a release includes breaking changes, a migration guide is added to `docs/MIGRATION.md`. See the [README](../README.md#migration-from-in-fork-plugin) for the most recent migration from the in-fork plugin version.
+
+## Deprecation policy
+
+Features are deprecated through one minor release before removal:
+1. Marked deprecated in `CHANGELOG.md` and a `DeprecationWarning` in code
+2. Removed in the next major version
+
+The dashboard's HTTP API follows [semver](https://semver.org/) — breaking endpoint changes bump a major version.

hyatlas_memory-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,321 @@
+# Contributing to HyAtlas-Memory
+
+> Thanks for your interest in contributing! This is a community implementation of the official [Hy-Memory framework](https://memory.hunyuan.tencent.com) by Tencent Hunyuan. All contributions are welcome — bug reports, docs, code, tests, and design feedback.
+
+## Code of conduct
+
+Be respectful. We're all here to build something useful. Disagreements are fine; personal attacks are not. Assume good faith. When in doubt, follow the [Contributor Covenant](https://www.contributor-covenant.org/).
+
+## What to work on
+
+The easiest ways to help, ordered roughly by impact:
+
+1. **Use it and report bugs** — Install, run, hit an edge case, open an issue with reproduction steps
+2. **Improve docs** — If something's unclear, fix it. PRs to `/docs` and `/README.md` are always welcome
+3. **Add tests** — The `tests/` directory could use more coverage
+4. **Add a new memory layer operation** — See "Adding a new feature" below
+5. **Improve the dashboard** — `server/dashboard/dashboard.html` is a single file; refactors welcome
+6. **Port a patch from upstream** — If a newer Hy-Memory SDK fixes something we patch around, port the patch
+
+## Reporting bugs
+
+Use [GitHub Issues](https://github.com/tuancookiez-hub/HyAtlas-Memory/issues). Include:
+
+- **What you did** (exact commands, in order)
+- **What you expected**
+- **What happened** (full error message, screenshot if visual)
+- **Environment:**
+  - OS + version
+  - Python version (`python --version`)
+  - Hermes Agent version (`hermes --version`)
+  - Package version (`pip show hyatlas-memory`)
+
+For dashboard bugs, also include the browser + version.
+
+## Suggesting features
+
+Open an issue with the `enhancement` label. Describe:
+- The use case (what you're trying to do)
+- The proposed solution (how it should work)
+- Alternatives you considered
+
+If it's a large change (new layer, new store, breaking change), start a discussion first.
+
+## Development setup
+
+### Prerequisites
+
+- Python 3.10+ (3.11+ recommended)
+- [uv](https://github.com/astral-sh/uv) (fast pip alternative) or pip
+- [Qdrant](https://qdrant.tech/) running locally (Docker, native, or via the project's scripts)
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed and on PATH
+- Git
+
+### Clone and install
+
+```bash
+git clone https://github.com/tuancookiez-hub/HyAtlas-Memory.git
+cd HyAtlas-Memory
+
+# Editable install with dev + test extras
+uv pip install -e ".[dev,test]"
+# or:
+pip install -e ".[dev,test]"
+```
+
+### Start Qdrant
+
+```bash
+# Docker (easiest)
+docker run -d -p 6333:6333 -p 6334:6334 \
+  -v $(pwd)/qdrant_data:/qdrant/storage \
+  --name hyatlas-qdrant \
+  qdrant/qdrant
+
+# Or use the project script (if present)
+python scripts/start_qdrant.py
+```
+
+Verify:
+```bash
+curl http://127.0.0.1:6333/collections
+# Should return: {"result":{"collections":[]}}
+```
+
+### Run tests
+
+```bash
+# All tests
+pytest
+
+# With coverage
+pytest --cov=hyatlas_memory --cov-report=term-missing
+
+# Integration tests only (need a running server)
+pytest -m integration
+
+# Specific test
+pytest tests/test_hy_memory_search.py::test_search_basic -v
+```
+
+### Run the linter
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/   # auto-format
+```
+
+### Run the dashboard
+
+```bash
+# In one terminal
+python -m server.start_server
+
+# In another
+python server/dashboard/dashboard.py
+# Open http://127.0.0.1:8765
+```
+
+### Run the L5 pipeline
+
+```bash
+# This rebuilds the Kuzu graph from scratch — takes minutes
+python server/bin/l5_full_pipeline.py
+```
+
+## Project structure
+
+```
+HyAtlas-Memory/
+├── src/hyatlas_memory/    # the plugin (Python package)
+│   ├── __init__.py        # HyMemoryProvider — entry point
+│   ├── client.py          # HTTP client to upstream
+│   ├── patches.py         # 9 SDK patches (applied at import)
+│   ├── context_pressure.py # 4-tier token budget monitor
+│   ├── process.py         # subprocess lifecycle
+│   ├── embed_server.py    # local embedder
+│   ├── init_wizard.py     # first-run setup
+│   ├── installer.py       # pip-deps installer
+│   ├── cli.py             # `hermes hy-memory ...` subcommands
+│   └── plugin.yaml        # legacy manifest
+│
+├── server/                 # standalone server
+│   ├── start_server.py    # uvicorn launcher
+│   ├── bin/               # L5 pipeline scripts
+│   └── dashboard/         # web UI (port 8765)
+│
+├── tests/                  # pytest suite
+├── docs/                   # architecture + API + troubleshooting
+├── assets/                 # screenshots, infographics
+├── examples/               # usage examples
+└── scripts/                # dev scripts (smoke_test, etc.)
+```
+
+## Coding style
+
+### Python
+
+- **Type hints** on all public functions
+- **Docstrings** on all public modules, classes, functions
+- **No `any`** in type hints — use `Any` if truly needed, but prefer specific types
+- **Imports**: stdlib first, then third-party, then local; alphabetized within each group
+- **Line length**: 100 chars (enforced by ruff)
+- **Quotes**: double quotes for strings, single for short dict keys
+- **Naming**: snake_case for functions/vars, PascalCase for classes, UPPER_SNAKE for constants
+
+### JavaScript (dashboard)
+
+- **No frameworks** — vanilla JS + Three.js, keep it that way unless absolutely necessary
+- **No build step** — the HTML is served as-is, you must be able to edit and refresh
+- **ES2020+** syntax is fine (the dashboard runs in modern browsers only)
+- **DOM access**: cache `getElementById` results, don't query in hot loops
+- **Event handlers**: clean up on `pagehide` / `beforeunload` to avoid memory leaks
+
+### Markdown
+
+- **One sentence per line** in source (wraps better in diffs)
+- **Code blocks** with language tags (`bash`, `python`, `json`, etc.)
+- **Links** relative within the repo (`./docs/...`), absolute for external (`https://...`)
+- **Headings**: title case, no trailing period
+
+## Testing
+
+### When to add a test
+
+- New public function in `src/hyatlas_memory/` → add a unit test in `tests/`
+- New API endpoint in `server/dashboard/dashboard.py` → add an integration test
+- Bug fix → add a regression test that fails before your fix
+- New CLI subcommand → add a test for the subcommand
+
+### Test conventions
+
+- **Test names**: `test_<unit_being_tested>_<scenario>` — e.g., `test_search_with_empty_query_returns_empty`
+- **Use fixtures** for shared setup, not module-level globals
+- **Mock external calls** (Qdrant, upstream server) — tests should run without those running
+- **One assertion per test** when possible (multiple asserts are OK if testing one behavior)
+- **Parametrize** for similar tests with different inputs
+
+Example:
+```python
+import pytest
+from hyatlas_memory import search
+
+def test_search_returns_results_above_threshold():
+    # ...
+    results = search("TypeScript", min_score=0.5)
+    assert all(r.score >= 0.5 for r in results)
+
+@pytest.mark.parametrize("query,expected_empty", [
+    ("", True),
+    ("   ", True),
+    ("!@#$", False),  # gibberish might match noise
+])
+def test_search_empty_query(query, expected_empty):
+    results = search(query)
+    assert (len(results) == 0) == expected_empty
+```
+
+## Adding a new feature
+
+### Adding a new memory layer operation
+
+1. Add the function in `src/hyatlas_memory/__init__.py` (or a new module)
+2. Add the corresponding HTTP endpoint in `server/dashboard/dashboard.py` if it needs dashboard support
+3. Add a test in `tests/`
+4. Update `docs/LAYERS.md` if it changes layer semantics
+5. Update the dashboard HTML if it needs UI representation
+
+### Adding a new API endpoint
+
+1. Add a new `if path == "/api/your-endpoint":` branch in `do_GET` / `do_POST`
+2. Use `self._json(status, payload)` to send responses
+3. Document it in `docs/API.md`
+4. Add an integration test in `tests/test_dashboard_api.py` (create if missing)
+
+### Adding a new dashboard page
+
+1. Add a `<div class="page-section" id="page-yourpage">...</div>` to the HTML
+2. Add a nav item in the sidebar
+3. Add a `renderYourPage()` function called from `renderAll()`
+4. Document it in `docs/DASHBOARD.md`
+
+### Adding a new patch
+
+Patches fix upstream SDK issues. If you're patching around something in the SDK:
+
+1. Add the patch to `src/hyatlas_memory/patches.py`
+2. Make it idempotent (safe to apply multiple times)
+3. Add a comment explaining **what** it fixes and **why** (with a link to the issue if there is one)
+4. Register it in the `patches = [...]` list at the bottom of the file
+5. Add a test that verifies the patch is applied (or at least doesn't error)
+
+## Pull request process
+
+1. **Fork the repo** and create a branch:
+   ```bash
+   git checkout -b fix/issue-123-search-typo
+   # or
+   git checkout -b feature/new-layer
+   ```
+
+2. **Make your changes** in small, focused commits:
+   ```bash
+   git add -p   # stage hunks, not whole files
+   git commit -m "fix(search): handle empty query without crashing
+
+   Empty queries were throwing AttributeError on .split() because the
+   upstream SDK doesn't guard against them. Added a check.
+
+   Closes #123"
+   ```
+
+3. **Run tests + linter locally:**
+   ```bash
+   pytest
+   ruff check src/ tests/
+   ```
+
+4. **Push and open a PR:**
+   ```bash
+   git push origin your-branch
+   gh pr create --fill   # or use the GitHub web UI
+   ```
+
+5. **PR description should include:**
+   - What changed and why
+   - How to test
+   - Screenshots/recordings for UI changes
+   - Linked issues (`Closes #123`)
+
+6. **Wait for review.** The maintainers will respond within a few days. Be patient — this is a hobby project.
+
+### Commit message style
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` — new feature
+- `fix:` — bug fix
+- `docs:` — docs only
+- `refactor:` — code change that doesn't add a feature or fix a bug
+- `test:` — add or fix tests
+- `chore:` — maintenance (deps, CI, etc.)
+
+Scope is optional but helpful: `fix(dashboard): handle empty layer counts`
+
+### After your PR is merged
+
+- Your contribution will be in the next release's [CHANGELOG.md](CHANGELOG.md)
+- You'll be added to the contributors list (or the GitHub auto-generated one)
+
+## Release process
+
+The maintainer (currently [@tuancookiez-hub](https://github.com/tuancookiez-hub)) cuts releases:
+
+1. Bump version in `pyproject.toml` and `src/hyatlas_memory/_version.py`
+2. Update `CHANGELOG.md` with the release notes
+3. Tag the commit: `git tag -a v0.X.0 -m "Release 0.X.0"`
+4. Push the tag: `git push origin v0.X.0`
+5. Build and publish to PyPI: `uv build && uv publish`
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](../LICENSE).

hyatlas_memory-1.0.0/LICENSE

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

hyatlas_memory-1.0.0/MANIFEST.in

@@ -0,0 +1,32 @@
+# HyAtlas-Memory — sdist manifest.
+# Ensures files outside the `src/` package tree ship in the source
+# distribution so PyPI users get a usable install (LICENSE, README,
+# docs/, pyproject.toml itself for source installs).
+
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+
+recursive-include docs *.md
+recursive-include server/dashboard/templates *.html *.css *.js
+recursive-include server/dashboard/static *.js *.css *.png *.svg
+recursive-include tests *.py
+recursive-include tests *.json
+
+# Exclude dev-only scratch from sdist
+exclude scripts/*.py
+exclude .github
+exclude .gitignore
+exclude .dockerignore
+exclude Dockerfile
+exclude docker-compose.yml
+
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *.pyd
+global-exclude .pytest_cache
+global-exclude .ruff_cache
+global-exclude .mypy_cache