{"id":51604892,"url":"https://github.com/kymuco/adaptive-reservoir","last_synced_at":"2026-07-12T01:01:45.598Z","repository":{"id":362460535,"uuid":"1255721057","full_name":"kymuco/adaptive-reservoir","owner":"kymuco","description":"CPU-friendly temporal adaptation layer for software agents and streaming systems.","archived":false,"fork":false,"pushed_at":"2026-06-14T10:52:40.000Z","size":133,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T11:26:06.039Z","etag":null,"topics":["adaptive-systems","agent-systems","behavior-adaptation","concept-drift","cpu-friendly","echo-state-network","edge-ai","machine-learning","online-learning","presence-engine","python","reservoir-computing","signal-processing","software-agents","streaming-data","temporal-modeling","time-series"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kymuco.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T05:41:06.000Z","updated_at":"2026-06-14T10:21:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kymuco/adaptive-reservoir","commit_stats":null,"previous_names":["kymuco/adaptive-reservoir"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kymuco/adaptive-reservoir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kymuco%2Fadaptive-reservoir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kymuco%2Fadaptive-reservoir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kymuco%2Fadaptive-reservoir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kymuco%2Fadaptive-reservoir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kymuco","download_url":"https://codeload.github.com/kymuco/adaptive-reservoir/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kymuco%2Fadaptive-reservoir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35378723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adaptive-systems","agent-systems","behavior-adaptation","concept-drift","cpu-friendly","echo-state-network","edge-ai","machine-learning","online-learning","presence-engine","python","reservoir-computing","signal-processing","software-agents","streaming-data","temporal-modeling","time-series"],"created_at":"2026-07-12T01:01:39.007Z","updated_at":"2026-07-12T01:01:45.555Z","avatar_url":"https://github.com/kymuco.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adaptive-reservoir\n\nA small online temporal adaptation layer for systems that need numeric reflexes,\nnot another LLM, agent framework, or memory database.\n\n`adaptive-reservoir` turns numeric event streams into predictions, metrics, and\nadaptive state channels such as drift pressure, confidence, interruption risk,\nor wait/notify hints.\n\nIt is designed to sit below a host system:\n\n```text\nnumeric feature stream\n        |\n        v\nadaptive-reservoir\n        |\n        v\npredictions / metrics / adaptive channels\n        |\n        v\nhost interpretation + policy + action layer\n```\n\n## Why this exists\n\nMany adaptive systems receive changing streams: interaction rhythm, system\npresence, practice-session signals, sensor-like events, and other numeric\nfeatures.\n\nStatic rules and one-shot predictions are often too brittle for those streams.\nThe useful question is not only \"what is happening now?\" but also:\n\n```text\nis the stream changing?\nis the system stable?\nshould the host wait, adapt, or ask for more context?\n```\n\n`adaptive-reservoir` provides a lightweight online substrate for those questions.\nIt helps a host system build a small numeric reflex layer while the host still\nowns meaning, memory, consent, policy, and actions.\n\n## What it is\n\n- A lightweight Python library for online temporal adaptation.\n- A CPU-friendly reservoir-style state engine.\n- A reusable substrate for software agents, presence engines, practice systems,\n  and streaming applications.\n- A foundation for adaptive state channels such as drift pressure, confidence,\n  saturation, stability, interruption risk, and wait/notify hints.\n- A deterministic benchmark and example suite for checking adaptation behavior.\n\n## What it is not\n\n- Not an LLM.\n- Not an agent framework.\n- Not a memory database.\n- Not HDE Core.\n- Not a consent, policy, identity, or audit layer.\n- Not a semantic interpreter.\n- Not a replacement for host-side privacy and safety checks.\n\n`adaptive-reservoir` processes numeric feature streams only. Host systems own raw\ndata access, feature extraction, interpretation, memory, consent, policy,\nactions, and audit.\n\n## When to use it\n\nUse `adaptive-reservoir` when you have a numeric stream and want online adaptive\nsignals that a host system can interpret.\n\nGood fits include:\n\n- concept-drift and temporal-drift experiments\n- adaptive state channels for agent-like systems\n- synthetic presence or interaction streams\n- practice-session dynamics\n- low-level numeric adaptation layers in larger systems\n- HDE-like hosts that need adaptive numeric channels but own policy elsewhere\n\nPoor fits include:\n\n- natural-language reasoning by itself\n- storing user memories\n- making policy decisions\n- enforcing consent\n- directly reading desktop, email, chat, or private documents\n- executing user-facing actions without a host decision layer\n\n## Quick start\n\nInstall locally for development:\n\n```bash\npython -m pip install -e .\npython -m pip install pytest ruff\n```\n\nRun a benchmark:\n\n```bash\nadaptive-reservoir-bench temporal-drift --format markdown\n```\n\nRun examples:\n\n```bash\npython examples/temporal_drift_demo.py\npython examples/behavior_bias_demo.py\npython examples/presence_state_demo.py\n```\n\nRun checks:\n\n```bash\npython -m pytest\npython -m ruff check .\n```\n\n## Examples\n\n### Temporal drift\n\nUse the benchmark runner when you want a compact, reproducible check that the\nmodel can adapt when a temporal stream changes:\n\n```bash\nadaptive-reservoir-bench temporal-drift --format markdown\n```\n\nOr run the executable demo:\n\n```bash\npython examples/temporal_drift_demo.py\n```\n\nThis demonstrates:\n\n```text\nstream -\u003e prediction -\u003e metrics\n```\n\n### Adaptive channels\n\n`adaptive-reservoir` can also be used as a low-level numeric layer for adaptive\nstate channels. The host application decides how to interpret the channels and\nwhat to do with them.\n\n```bash\npython examples/behavior_bias_demo.py\npython examples/presence_state_demo.py\n```\n\nThese demos use deterministic synthetic numeric streams only:\n\n```text\nevents -\u003e adaptive channels -\u003e host decision hints\n```\n\nThey do not read real desktop activity, process message content, infer real user\nstate, or integrate with Character_OS/HDE.\n\n## Benchmarks\n\nThe benchmark suite is intentionally deterministic and synthetic. It is evidence\nfor online temporal adaptation behavior, not a production-readiness claim.\n\nCurrent benchmarks:\n\n| Benchmark | What it stresses |\n|---|---|\n| `concept-drift` | abrupt input-to-target mapping change |\n| `temporal-drift` | changed temporal dependency / delay |\n| `delayed-xor` | delayed memory plus nonlinear binary logic |\n\nBenchmark reports include metrics such as `final_score`, `adapt_steps`,\n`us_per_sample`, `saturation_rate`, and `readout_sparsity`.\n\nSee [Benchmark Methodology](docs/benchmarks.md) for how to read the results and\nwhat they do not prove.\n\n## Documentation map\n\n- [Adaptive State Channels](docs/adaptive_state_channels.md) explains channel\n  meaning, computation, ranges, interpretation, and limitations.\n- [Benchmark Methodology](docs/benchmarks.md) explains why the benchmark suite\n  uses concept drift, temporal drift, and delayed XOR.\n- [HDE Integration Note](docs/integration/hde.md) defines the boundary between\n  `adaptive-reservoir` and HDE-like host systems.\n- [Character OS Design Note](docs/integration/character_os.md) sketches a\n  companion-facing adapter boundary.\n- [Machine Presence Design Note](docs/integration/machine_presence.md) sketches a\n  system-presence adapter boundary.\n- [PracticeLens Design Note](docs/integration/practicelens.md) sketches a\n  practice-session adapter boundary.\n\n## Development\n\nRun the local checks:\n\n```bash\npython -m pip install -e .\npython -m pip install pytest ruff\npython -m pytest\npython -m ruff check .\n```\n\n## License\n\nApache-2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkymuco%2Fadaptive-reservoir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkymuco%2Fadaptive-reservoir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkymuco%2Fadaptive-reservoir/lists"}