stark-ai-de/agent-skills / incubator/skills/engineering-workflows/hindsight-memory
hindsight-memory
VerifiedSet up, diagnose, enable or use scoped Hindsight memory without requiring Greppy. Use when the user requests approved project or workspace memory, compact Codex/pi session outcomes or source-backed reflection. Not for global memory cleanup or implicit ingestion of search-indexed repositories.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.4 KB |
| assets/compose.yaml | config | 2.7 KB |
| assets/parser.nix | other | 783 B |
| assets/project.example.json | config | 873 B |
| assets/workspace.example.json | config | 1.1 KB |
| diagnostics/bank_aliases.py | script | 7.0 KB |
| diagnostics/workspace_status.py | script | 2.8 KB |
| references/setup.md | markdown | 23.9 KB |
| scripts/activate.py | script | 3.2 KB |
| scripts/build_parser.py | script | 2.6 KB |
| scripts/initialize.py | script | 5.1 KB |
| scripts/mcp_launcher.py | script | 9.1 KB |
| scripts/metrics.py | script | 4.6 KB |
| scripts/private_policy.py | script | 1.4 KB |
| scripts/project_scope.py | script | 13.7 KB |
| scripts/session_hook.py | script | 6.1 KB |
| scripts/session_parser.py | script | 11.0 KB |
| scripts/weekly.py | script | 19.5 KB |
| scripts/worker.py | script | 8.8 KB |
| scripts/workspace_scope.py | script | 13.1 KB |
scripts/mcp_launcher.py
View on GitHub"""Start the local MCP transport with a credential from the private env file."""
import argparse
from contextlib import contextmanager
import http.client
import json
import os
from pathlib import Path
import re
import shlex
import signal
import stat
import sys
import time
import urllib.error
import urllib.request
from urllib.parse import urlsplit
from project_scope import project_directory
_BANK_HTTP_SECONDS = 5.0
class BankBootstrapError(ValueError):
"""A bounded, nonsecret bank-startup diagnostic."""
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
@contextmanager
def _bank_deadline(deadline):
"""Interrupt blocking headers/body reads on the supported Linux/WSL host."""
remaining = deadline - time.monotonic()
if remaining <= 0:
raise BankBootstrapError("Hindsight workspace bank startup exceeded its five-second HTTP budget.")
if any(signal.getitimer(signal.ITIMER_REAL)):
raise BankBootstrapError("Hindsight workspace bank startup cannot replace an existing process timer.")
def expired(signum, frame):
raise BankBootstrapError("Hindsight workspace bank startup exceeded its five-second HTTP budget.")
try:
previous = signal.signal(signal.SIGALRM, expired)
except ValueError:
raise BankBootstrapError("Hindsight workspace bank startup requires the launcher main thread.") from None
try:
signal.setitimer(signal.ITIMER_REAL, remaining)
yield
finally:
signal.setitimer(signal.ITIMER_REAL, 0)
signal.signal(signal.SIGALRM, previous)
def ensure_workspace_bank(endpoint, bank_id, token, revalidate):
"""Make a qualified workspace's exact bank readable before its first retain.
Hindsight 1.2.1 does not create banks during reads. PUT {} initializes only
an absent bank profile; it supplies no facts, name or configuration changes.
"""
url = urlsplit(endpoint)
if (url.scheme != "http" or url.hostname not in {"127.0.0.1", "localhost", "::1"}
or not url.port or url.username is not None or url.password is not None
or url.query or url.fragment or url.path not in {"", "/"}
or not isinstance(bank_id, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}", bank_id)
or not isinstance(token, str) or not token
or any(ord(character) < 33 or ord(character) > 126 for character in token)):
raise BankBootstrapError("Hindsight workspace bank endpoint or credential is invalid.")
base = endpoint.rstrip("/") + "/v1/default/banks/" + bank_id
deadline = time.monotonic() + _BANK_HTTP_SECONDS
opener = urllib.request.build_opener(urllib.request.ProxyHandler({}), NoRedirect())
def request(method, suffix):
remaining = deadline - time.monotonic()
if remaining <= 0:
raise BankBootstrapError("Hindsight workspace bank startup exceeded its five-second HTTP budget.")
req = urllib.request.Request(base + suffix, data=b"{}" if method == "PUT" else None, method=method,
headers={"Authorization": "Bearer " + token, "Accept": "application/json", "Content-Type": "application/json"})
try:
with opener.open(req, timeout=remaining) as response:
status = response.status
raw = response.read(1048577)
except urllib.error.HTTPError as error:
status = error.code
error.close()
return status, None
except (OSError, urllib.error.URLError, http.client.HTTPException):
raise BankBootstrapError("Hindsight workspace bank request failed or timed out.") from None
if len(raw) > 1048576 or time.monotonic() > deadline:
raise BankBootstrapError("Hindsight workspace bank response exceeded its size or time bound.")
try:
result = json.loads(raw)
except (ValueError, UnicodeError, RecursionError):
raise BankBootstrapError("Hindsight workspace bank returned invalid JSON.") from None
return status, result
def checked(status, result, *, configuration=False):
if status != 200:
raise BankBootstrapError(f"Hindsight workspace bank request returned HTTP {status}.")
if (not isinstance(result, dict) or result.get("bank_id") != bank_id
or "error" in result or result.get("success") is False
or result.get("status") in ("error", "failed")
or (configuration and (not isinstance(result.get("config"), dict)
or not isinstance(result.get("overrides"), dict)))):
raise BankBootstrapError("Hindsight workspace bank response did not verify the exact mapped bank.")
with _bank_deadline(deadline):
revalidate()
status, result = request("GET", "/config")
if status == 404:
revalidate()
checked(*request("PUT", ""))
status, result = request("GET", "/config")
checked(status, result, configuration=True)
revalidate()
def launch(path, proxy, policy_path=None, workspace_policy_path=None):
if os.environ.get("HINDSIGHT_MEMORY_DISABLED") == "1":
raise SystemExit("Hindsight is disabled for this client session.")
endpoint = "http://127.0.0.1:18888/mcp/greppy/"
if policy_path and workspace_policy_path:
raise ValueError("choose one memory policy")
if workspace_policy_path:
from workspace_scope import load, active, local_active, resolve
from project_scope import private_read
scope = load(workspace_policy_path)
inputs = {Path(workspace_policy_path), Path(scope["stateRoot"]) / "activation.json", Path(scope["runtimeEnv"])}
snapshot = {item: private_read(item) for item in inputs}
cutoff = active(scope)
cwd = Path.cwd()
repository = resolve(scope, cwd, register=True)
path = Path(scope["runtimeEnv"])
endpoint = scope["endpoint"].rstrip("/") + "/mcp/" + repository["bankId"] + "/"
def revalidate():
# The full route was checked above. Keep this local guard bounded;
# repeated Docker/model metadata calls would consume client startup.
if (os.environ.get("HINDSIGHT_MEMORY_DISABLED") == "1"
or any(private_read(item) != original for item, original in snapshot.items())
or load(workspace_policy_path) != scope or local_active(scope) != cutoff
or resolve(scope, cwd) != repository):
raise BankBootstrapError("Hindsight workspace scope changed before MCP startup.")
elif policy_path:
from project_scope import load, active
scope = load(policy_path)
active(scope)
project_directory(Path.cwd(), scope["projectRoot"])
if Path(path).resolve() != Path(scope["runtimeEnv"]):
raise SystemExit("MCP runtime environment differs from project policy.")
endpoint = scope["endpoint"].rstrip("/") + "/mcp/" + scope["bankId"] + "/"
if not policy_path and not workspace_policy_path and not (Path.home() / ".local/state/hindsight-greppy/pilot-start").is_file():
raise SystemExit("Hindsight MCP becomes available after pilot qualification.")
try:
fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
with os.fdopen(fd, encoding="utf-8") as stream:
info = os.fstat(stream.fileno())
if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) != 0o600:
raise ValueError("permissions")
token = None
for line in stream:
name, separator, raw = line.rstrip().partition("=")
if separator and name == "HINDSIGHT_API_TENANT_API_KEY":
if token is not None:
raise ValueError("duplicate")
parts = shlex.split(raw)
if len(parts) != 1:
raise ValueError("value")
token = parts[0]
if not token:
raise ValueError("missing")
except (OSError, ValueError):
raise SystemExit("Hindsight requires an owned mode-0600 runtime.env with a local API key.") from None
if workspace_policy_path:
ensure_workspace_bank(scope["endpoint"], repository["bankId"], token, revalidate)
env = dict(os.environ)
env.update(API_ACCESS_TOKEN=token, NO_PROXY="127.0.0.1,localhost", no_proxy="127.0.0.1,localhost")
os.execve(proxy, [proxy, "--transport", "streamablehttp", endpoint], env)
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("runtime", type=Path)
parser.add_argument("proxy")
selected = parser.add_mutually_exclusive_group()
selected.add_argument("--policy", type=Path)
selected.add_argument("--workspace-policy", type=Path)
args = parser.parse_args()
try:
launch(args.runtime, args.proxy, args.policy, args.workspace_policy)
except BankBootstrapError as error:
raise SystemExit(str(error)) from None
except Exception:
raise SystemExit("MCP project scope or effective route could not be verified.") from None
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |