[andy-vdg]

✍️ Description

New script: Hindsight, an open-source memory server for AI agents (MIT, Python). Agents store conversations and documents in memory banks, then recall facts, entities and their history, or reflect on them, through a REST API, SDKs and a built-in MCP server.

• ct/hindsight.sh, install/hindsight-install.sh, json/hindsight.json.
• Install: fetch_and_deploy_gh_release … "tarball", then setup_uv with Python 3.11 and uv sync --locked --package hindsight-api-slim --extra local-ml, the same lockfile and extras as upstream's Dockerfile. The embedding and reranker models the Dockerfile preloads (BAAI/bge-small-en-v1.5, cross-encoder/ms-marco-MiniLM-L-6-v2) are downloaded during install, so the first start needs no network.
• Database: PostgreSQL 18 with pgvector via setup_postgresql / setup_postgresql_db (extensions vector, pg_trgm, btree_gin). Upstream's embedded pg0 database is not used: its initdb refuses to run as root.
• Config: /opt/hindsight.env; data and model cache: /opt/hindsight_data. Both are outside the deploy target, so the update needs no backup.
• LLM: Hindsight uses an LLM for fact extraction and reflect. The provider, key, model and base URL are app_vars (var_llm_provider, var_llm_api_key, var_llm_model, var_llm_base_url); nothing is asked inside the container. Left empty, Hindsight starts with its none provider (memories are stored as plain chunks, no extraction or reflect), and the install ends with a msg_warn naming the file to edit. For a local LLM, the base URL can point at the Ollama script's container (http://<ollama-ip>:11434/v1).
• Authentication: upstream ships the API with no authentication. Because Hindsight holds agents' memories, the install turns on upstream's built-in ApiKeyTenantExtension with a key from random_password 48, saved to ~/hindsight.creds (mode 600) next to the database login. The REST API and the MCP endpoint then need Authorization: Bearer <key>; /health and /docs stay open. The closing message and a json note say where the key is. The API listens on 0.0.0.0:8888, like the Dockerfile.
• Update: check_for_gh_release, CLEAN_INSTALL=1 redeploy, uv sync again.

Upstream research: docker/standalone/Dockerfile (python:3.11-slim, uv sync --locked … --extra local-ml --extra embedded-db, model preload, EXPOSE 8888, HINDSIGHT_API_HOST=0.0.0.0); hindsight_api/pg0.py for the embedded database; hindsight_api/config.py for the variables; the alembic migrations for the extensions they create.

🔗 Related PR / Issue

Link: None

✅ Prerequisites (X in brackets)

• Self-review completed – Code follows project standards.
• Tested thoroughly – Changes work as expected.
• No breaking changes – Existing functionality remains intact.
• No security risks – No hardcoded secrets, unnecessary privilege escalations, or permission issues.

---

🏗️ arm64 Support (X in brackets)

• arm64 supported - Tested and supported on arm64.
• arm64 not tested - Assumed to work on arm64, but testing has not been done.
• arm64 not supported - Confirmed upstream dependencies or binaries do not support arm64.

No arm64 host available, so var_arm64 is left unset (the user is asked) and the json has no architectures. The lockfile pins CPU torch wheels for x86_64; arm64 wheels exist upstream but are untested here.

---

🖥️ Tested on (X in brackets)

• Proxmox VE – Created on a Proxmox VE host and the app works.
• Incus – Created on an Incus host and the app works.

Application containers run on both; tick what you actually tested. VMs and host tools are Proxmox only.

Proxmox VE 9, Debian 13 template, unprivileged:

• unattended create with the LLM values preset, and two interactive creates through the advanced menus with no LLM set;
• health endpoint 200 with the database connected; a memory retained and recalled through the API (none provider);
• API key: retain without a key or with a wrong key → 401, with the key → 200; MCP initialize without the key → 401, with it → 200; /health and /docs → 200;
• pct reboot: service back, health 200;
• update path from a lowered ~/.hindsight: 1.0.0 → 1.1.0 deployed, uv sync rebuilt the environment, config unchanged, the stored memory still recalled.

---

🛠️ Type of Change (X in brackets)

• 🐞 Bug fix – Resolves an issue without breaking functionality.
• ✨ New feature – Adds new, non-breaking functionality.
• 💥 Breaking change – Alters existing functionality in a way that may require updates.
• 🆕 New script – A fully functional and tested script or script set.
• 🌍 Website update – Changes to website-related JSON files or metadata.
• 🔧 Refactoring / Code Cleanup – Improves readability or maintainability without changing functionality.
• 📝 Documentation update – Changes to README, AppName.md, CONTRIBUTING.md, or other docs.

---

🔍 Code & Security Review (X in brackets)

• Follows CODE-AUDIT.md & CONTRIBUTING.md guidelines
• Uses correct script structure (AppName.sh, AppName-install.sh, AppName.json)
• No hardcoded credentials
• No Docker / Docker Compose – The application is installed bare-metal; Docker is not used.
• No git pull – Updates use fetch_and_deploy_gh_release, fetch_and_deploy_codeberg_release, fetch_and_deploy_gl_release, or fetch_and_deploy_from_url instead of git pull.

---

🤖 AI Assistance (X in brackets)

If you used an AI tool (GitHub Copilot, Claude, ChatGPT, etc.) to write or generate any scripts in this PR, you must confirm compliance below.
Select exactly one option.

• No AI used – Scripts were written without AI assistance.
• AI was used – I confirm the scripts were built using AGENTS.md and .github/agents/pve-script-creator.agent.md as guidance, and the output has been reviewed and corrected to match those guidelines.

Claude Opus 5.5 (Anthropic), medium reasoning, in Claude Code: read upstream's Dockerfile and source, drafted the scripts and the JSON from AGENTS.md, and ran the test builds on my Proxmox hosts. I made the design decisions, ran the interactive installs and reviewed the result.

---

📋 Additional Information (optional)

The generated API key departs from upstream's default (no authentication). If upstream's default is preferred, the change is the two HINDSIGHT_API_TENANT_* lines and the creds block; they can be swapped for a warning note.

---

📦 Application Requirements (for new scripts)

⚠️ Do not remove this section.
It is used by automated PR validation checks.
If this PR is not a new script submission, leave the checkboxes unchecked.

Required for 🆕 New script submissions.
Pull requests that do not meet these requirements may be closed without review.

• The application is at least 6 months old
• The application is actively maintained
• The application has 600+ GitHub stars
• Official release tarballs are published
• I understand that not all scripts will be accepted due to various reasons and criteria by the community-scripts ORG

🌐 Source

• https://github.com/vectorize-io/hindsight
• https://hindsight.vectorize.io/

[github-actions]

Try this script

ct/hindsight.sh, run in the Proxmox VE shell or on an Incus host:

COMMUNITY_SCRIPTS_URL=https://raw.githubusercontent.com/andy-vdg/DevScripts/hindsight \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/andy-vdg/DevScripts/hindsight/ct/hindsight.sh)"

COMMUNITY_SCRIPTS_URL is not optional for ct/. Fetching the ct/ script from a
branch does not tell the engine where that branch is — with bash -c "$(curl …)"
there is no file on disk for the scripts root to be derived from, so it would fall
back to upstream main and look for the install script there.

Against a core branch as well

Add COMMUNITY_SCRIPTS_CORE_URL=https://raw.githubusercontent.com/OWNER/core/BRANCH
to test an engine change at the same time. The two resolve independently.

Useful flags while testing

dev_mode=net logs every fetch with status and duration, so you can confirm the
branch is really being used. dev_mode=keep stops a failed build from deleting
the container along with the evidence.