{"id":51048193,"url":"https://github.com/tom-wang898/memory-runtime","last_synced_at":"2026-06-22T15:01:09.055Z","repository":{"id":350984603,"uuid":"1208267334","full_name":"Tom-Wang898/memory-runtime","owner":"Tom-Wang898","description":"Automatic hot/cold memory runtime for Codex, Claude, and Gemini that saves tokens without rewriting the prompt.","archived":false,"fork":false,"pushed_at":"2026-04-28T08:56:55.000Z","size":5181,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T10:34:37.632Z","etag":null,"topics":["agent-memory","ai-agents","claude","cli","codex","context-engineering","developer-tools","docker","gemini","llm","memory","memory-palace","sqlite","token-optimization"],"latest_commit_sha":null,"homepage":"https://github.com/Tom-Wang898/memory-runtime","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tom-Wang898.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-12T03:33:20.000Z","updated_at":"2026-04-28T08:56:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Tom-Wang898/memory-runtime","commit_stats":null,"previous_names":["tom-wang898/memory-runtime"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Tom-Wang898/memory-runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tom-Wang898%2Fmemory-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tom-Wang898%2Fmemory-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tom-Wang898%2Fmemory-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tom-Wang898%2Fmemory-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tom-Wang898","download_url":"https://codeload.github.com/Tom-Wang898/memory-runtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tom-Wang898%2Fmemory-runtime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34653715,"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-06-22T02:00:06.391Z","response_time":106,"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":["agent-memory","ai-agents","claude","cli","codex","context-engineering","developer-tools","docker","gemini","llm","memory","memory-palace","sqlite","token-optimization"],"created_at":"2026-06-22T15:01:03.819Z","updated_at":"2026-06-22T15:01:09.048Z","avatar_url":"https://github.com/Tom-Wang898.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# memory-runtime\n\n![memory-runtime social preview](./assets/social-preview-github.png)\n\n[![CI](https://github.com/Tom-Wang898/memory-runtime/actions/workflows/ci.yml/badge.svg)](https://github.com/Tom-Wang898/memory-runtime/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/Tom-Wang898/memory-runtime?include_prereleases\u0026display_name=tag)](https://github.com/Tom-Wang898/memory-runtime/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-6BE1C6.svg)](./LICENSE)\n[![Node 22+](https://img.shields.io/badge/node-22%2B-5FA04E.svg)](./package.json)\n\n`memory-runtime` gives Codex, Claude, and Gemini a compact hot/cold memory layer\nfor project context.\n\nIt saves tokens without rewriting the user request, stays fail-open when memory\nproviders are unavailable, and keeps host integrations replaceable.\n\nUse it when you want:\n\n- automatic project bootstrap for CLI agents\n- local hot memory with optional Memory Palace cold memory\n- safer recall for short references like `route A`, `this`, or `that`\n- explicit local skill governance without silent edits\n- public-repo-friendly export tooling for sanitized memory assets\n\nQuick links:\n\n- Chinese quick start: `README_CN.md`\n- Docker cold memory: `docs/COLD_MEMORY_DOCKER.md`\n- Codex app integration: `docs/CODEX_APP.md`\n- Configuration: `docs/CONFIGURATION.md`\n- Setup guide: `docs/SETUP.md`\n- Privacy and safe publishing: `docs/PRIVACY.md`\n- Memory Palace project tools: `docs/MEMORY_PALACE_PROJECT_TOOLS.md`\n- Public export workflow: `docs/PUBLIC_EXPORT.md`\n- Troubleshooting: `docs/TROUBLESHOOTING.md`\n- Changelog: `CHANGELOG.md`\n\n## Current status\n\nThis repo is ready for public GitHub use as an `0.x` GitHub-first runtime:\n\n- hot memory is backed by local SQLite via `node:sqlite`\n- cold memory can use a real Memory Palace backend\n- Claude and Gemini wrappers are implemented\n- Codex stays native and uses `AGENTS + hmctl` for memory integration\n- Codex can optionally enable the hot-only `memory-hot` MCP without enabling the full runtime MCP\n- shell integration can be installed with one command\n- cold-memory autostart is optional and fail-open\n- ambiguous short references are anchor-expanded or cold-recall-suppressed\n- local skill governance supports audit, explicit apply, rollback, and benchmark flows\n\nThe current distribution model is:\n\n- clone from GitHub\n- run locally\n- install shell integration into `zsh` or `bash`\n- optionally audit, apply, rollback, and benchmark local skill governance\n\nIt is not an npm-published product yet.\n\n## Architecture\n\nThe runtime is split into replaceable layers:\n\n- `memory-core`: contracts, token budget policy, routing rules\n- `hot-memory-sqlite`: fast local hot-state provider\n- `cold-memory-memory-palace`: cold-memory adapter for Memory Palace\n- `cold-memory-fixture`: deterministic fixture adapter for tests and benchmarks\n- `host-codex`: Codex bootstrap and checkpoint integration surface\n- `host-claude`: Claude-oriented bootstrap rendering surface\n- `memory-hot-mcp`: optional hot-only MCP for local SQLite state and continuity\n- `mcp-bridge`: optional stdio bridge for inspection and promotion flows\n\n```text\nCLI host\n-\u003e host adapter\n-\u003e memory-core\n-\u003e hot provider\n-\u003e cold provider\n```\n\n## Design goals\n\n- high cohesion, low coupling\n- fail-open behavior that never blocks normal development\n- fast local bootstrap with strict latency and token budgets\n- replaceable hot and cold memory providers\n- ambiguous short references should recall less rather than recall wrong\n- public-repo-friendly code with no bundled personal memory data\n\n## Prerequisites\n\n- Node.js `22+` with `node:sqlite` support\n- npm `10+`\n- at least one supported host CLI already installed: Codex, Claude, or Gemini\n- `zsh` or `bash` if you want shell helpers such as `hmctl`\n- optional: a running Memory Palace backend for cold recall\n- optional for Docker cold memory: Docker with `docker compose`\n\n## Quick start\n\n1. Clone the repo and install dependencies:\n\n```bash\ngit clone https://github.com/Tom-Wang898/memory-runtime.git\ncd memory-runtime\nnpm install\n```\n\n2. Install shell integration:\n\n```bash\n./scripts/install-shell-integration.sh --shell zsh\n```\n\nUse `--shell bash` if you want `~/.bashrc` instead.\n\n3. Reload the shell:\n\n```bash\nsource ~/.zshrc\n```\n\n4. Verify the shell helpers and routed context path:\n\n```bash\ncodex --help\nclaude --help\ngemini --help\nhmctl primer --cwd \"$(pwd)\" --mode warm --json\nhmctl continuity --cwd \"$(pwd)\" --json\nhmctl context --cwd \"$(pwd)\" --query \"continue with the current route\" --json\nhmctl bootstrap --cwd \"$(pwd)\" --mode warm --query \"runtime smoke test\" --json\n```\n\nExpected:\n\n- `codex` stays the native host CLI\n- `hmctl` is available as the memory sidecar command\n- `hmctl primer` returns a compact primer and writes a cache file\n- `hmctl continuity` returns a compact active-state recovery pack\n- `hmctl context` auto-routes between primer, continuity, and bootstrap\n- `hmctl bootstrap` returns the fuller fallback payload for query-specific recall\n- `claude` and `gemini` may still be wrapped through shell integration\n\nIf you stop here, the runtime already works in hot-memory mode and will fail open\nif cold memory is unavailable.\n\n## Why routed context saves tokens\n\nThe normal Codex path is:\n\n1. read a tiny cached primer\n2. use continuity for continuation-style queries\n3. only fall back to full bootstrap when the task needs more context\n\nThat matters because both primer and continuity are intentionally smaller than the\nfull Codex bootstrap envelope:\n\n- primer keeps only a short background line plus a few deduplicated points\n- continuity keeps the current route, pinned constraints, next step, and active open loops\n- primer is cached per project, so repeated project turns do not have to rebuild full context\n- continuity is cached separately, so “continue / route A / next step” style turns do not need full bootstrap\n- bootstrap still uses the same hot/cold runtime, but it is reserved for query-specific recall\n\nRun this to compare the sizes:\n\n```bash\nnpm run bench:tokens\n```\n\nThat benchmark reports token estimates for:\n\n- compact primer text\n- continuity text\n- full Codex bootstrap envelope\n- naive JSON-sized context\n\n5. Optional: audit local skills without editing them:\n\n```bash\nhmctl skills-audit\n```\n\nYou can also point it at one explicit tree:\n\n```bash\nhmctl skills-audit --root \"$HOME/.codex/skills\" --json\n```\n\n6. Optional: generate a safe mutation plan first:\n\n```bash\nhmctl skills-plan --root \"$HOME/.codex/skills\" --host codex\n```\n\n7. Optional: apply managed changes with an automatic snapshot:\n\n```bash\nhmctl skills-apply --root \"$HOME/.codex/skills\" --host codex\n```\n\n8. Optional: rollback from a snapshot:\n\n```bash\nhmctl skills-rollback --snapshot \"$HOME/.memory-runtime/skill-governance/snapshots/\u003csnapshot\u003e.json\"\n```\n\n9. Optional: export duplicate-skill decisions:\n\n```bash\nhmctl skills-duplicates --root \"$HOME/.codex/skills\" --decision-out /tmp/duplicate-decisions.json\n```\n\n10. Optional: apply duplicate decisions without deleting files:\n\n```bash\nhmctl skills-duplicates-apply --decision-file /tmp/duplicate-decisions.json\n```\n\nYou can edit the exported decision file first.\nSet `action` to `skip` if a duplicate group should remain untouched.\nThe duplicate report now includes per-path status and token metadata, and apply results include before/after deltas.\nDuplicate groups are now ordered by review risk so the ugliest sets float to the top first.\n\n11. Optional: stage a sanitized public export from a private Codex or Memory Palace checkout:\n\n```bash\nhmctl public-export --list-profiles\nhmctl public-export --profile codex-project-memory --source /path/to/codex --output /tmp/codex-public-export\nhmctl public-export --profile memory-palace-project-tools --source /path/to/Memory-Palace --output /tmp/memory-palace-public-export\n```\n\nThat command only copies allowlisted files, replaces machine-specific paths with placeholders such as `${HOME}` and `${CODEX_REPO_ROOT}`, and fails if a private absolute path marker survives redaction.\n\nSee `docs/PUBLIC_EXPORT.md` for the full staging and mirror workflow.\n\n## Optional cold-memory setup\n\nCold memory uses Memory Palace.\n\nIf you already run Memory Palace somewhere, set its base URL:\n\n```bash\nexport MEMORY_RUNTIME_MP_BASE_URL=\"http://127.0.0.1:18000\"\n```\n\n### Recommended Docker path\n\nIf you want a stable cold-memory setup without cloning the full Memory Palace\nrepo, use the backend-only installer:\n\n```bash\n./scripts/install-memory-palace-docker.sh\nsource ~/.memory-runtime/env.sh\n```\n\nThat path:\n\n- deploys the official GHCR backend image only\n- generates a local API key by default\n- enables the `projects` domain needed by `memory-runtime`\n- writes shell exports to `~/.memory-runtime/env.sh`\n\n### Existing full Memory Palace deployment\n\nIf you want `memory-runtime` to auto-start a local Memory Palace backend, also set:\n\n```bash\nexport MEMORY_RUNTIME_MP_AUTOSTART=1\nexport MEMORY_RUNTIME_MP_BACKEND_ROOT=/absolute/path/to/Memory-Palace/backend\n```\n\nAutostart only attempts to run when:\n\n- `MEMORY_RUNTIME_MP_AUTOSTART=1`\n- the base URL is a loopback address\n- the backend root contains both `main.py` and `.venv/bin/python`\n\nIf any of those checks fail, the runtime degrades gracefully and continues.\n\nDocker deployments are treated differently:\n\n- the wrapper does not try to start or stop Docker for you\n- use `install-memory-palace-docker.sh` once, then keep `MEMORY_RUNTIME_MP_AUTOSTART=0`\n- if you want the full Dashboard and SSE stack, use the official Memory Palace repo\n\nSee:\n\n- `docs/COLD_MEMORY_DOCKER.md`\n- `docs/CONFIGURATION.md`\n- `docs/SETUP.md`\n- `docs/PRIVACY.md`\n\n## What gets installed\n\nThe shell installer injects a managed block into your shell rc file and wires:\n\n- `hmctl`\n- `memory_runtime_bridge`\n- `memory_runtime_prime`\n- `claude`\n- `gemini`\n\nIt leaves `codex` native.\n\nCodex MCP support is split on purpose:\n\n- `memory-hot` can be enabled for local SQLite hot memory\n- `memory-palace` can be enabled for explicit durable cold memory\n- the full `memory-runtime` MCP should stay disabled on the startup path\n\nThe installed sidecar path:\n\n- warms compact primer files in the background when you enter a real project directory\n- lets native Codex route reads through `hmctl context` or explicit `primer / continuity / bootstrap`\n- keeps `hmctl continuity` available for continuation-style turns without full bootstrap cost\n- keeps full `hmctl bootstrap` available when the task needs richer context\n- prefers project hot-layer memory from `projects://\u003cslug\u003e/digest/current` and `projects://\u003cslug\u003e/anchors/current` when the cold backend provides them\n- keeps the raw user prompt intact\n- avoids polluting hot memory with synthetic wrapper summaries\n- keeps heavy consolidation out of the synchronous startup path\n\nClaude and Gemini wrappers still exist for users who want wrapped shell flows on\nthose hosts, but native Codex should not depend on them.\n\nThe skill audit companion:\n\n- scans local skill trees only when you call it\n- reports token-heavy and host-coupled skills\n- supports explicit apply and rollback with snapshots\n- supports explicit duplicate review and quarantine decisions\n- does not auto-edit private skill directories unless you run `skills-apply`\n\n## Validation\n\nRun the full verification suite:\n\n```bash\nnpm run check:all\n```\n\nOptional benchmarks:\n\n```bash\nnpm run bench:bootstrap\nnpm run bench:tokens\nnpm run bench:skills-governance\n```\n\nUseful runtime commands:\n\n```bash\nhmctl context --cwd \"$(pwd)\" --query \"continue\" --json\nhmctl continuity --cwd \"$(pwd)\" --json\nhmctl compact --cwd \"$(pwd)\" --dry-run\nhmctl bootstrap --cwd \"$(pwd)\" --mode warm --query \"debug query\" --json\nhmctl checkpoint --cwd \"$(pwd)\" --summary \"checkpoint summary\"\nhmctl inspect --cwd \"$(pwd)\"\nhmctl metrics --cwd \"$(pwd)\"\n```\n\n## Repository docs\n\n- `docs/ARCHITECTURE.md`\n- `docs/COLD_MEMORY_DOCKER.md`\n- `docs/CODEX_APP.md`\n- `docs/DATA_CONTRACTS.md`\n- `docs/CONFIGURATION.md`\n- `docs/SETUP.md`\n- `docs/PRIVACY.md`\n- `docs/MEMORY_PALACE_PROJECT_TOOLS.md`\n- `docs/PUBLIC_EXPORT.md`\n- `docs/SAFETY.md`\n- `docs/SOCIAL_PREVIEW.md`\n- `docs/TROUBLESHOOTING.md`\n- `docs/OPEN_SOURCE.md`\n- `docs/RELEASE.md`\n- `docs/SKILL_GOVERNANCE.md`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-wang898%2Fmemory-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftom-wang898%2Fmemory-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-wang898%2Fmemory-runtime/lists"}