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/session_hook.py
View on GitHub#!/usr/bin/env python3
"""Quick local checkpoints for approved Codex/pi sessions; never call a service."""
import argparse
import datetime
import subprocess
import fcntl
import json
import os
from pathlib import Path
import re
import sys
import tempfile
from project_scope import project_directory
from session_parser import SESSION_ID, read_header, timestamp
def queue_session(event, home, policy_path=None, workspace_policy_path=None):
home = Path(home)
checkpoint_at = datetime.datetime.now(datetime.timezone.utc)
scope = None
mapping = None
if policy_path and workspace_policy_path:
return False
if (os.environ.get("HINDSIGHT_MEMORY_DISABLED") == "1" or event.get("memory_disabled") is True
or event.get("is_subagent") is True or event.get("hook_event_name") not in {"SessionEnd", "Stop"}):
return False
source = event.get("source", "codex")
if source not in {"codex", "pi"}:
return False
if workspace_policy_path:
import workspace_scope
try:
scope = workspace_scope.load(workspace_policy_path)
cutoff = workspace_scope.local_active(scope)
transcript = workspace_scope.transcript_path(scope, source, event["transcript_path"])
meta = read_header(transcript, source)
if not cutoff <= timestamp(meta["timestamp"]) <= checkpoint_at:
return False
mapping = workspace_scope.resolve(scope, event["cwd"], register=True)
if workspace_scope.resolve(scope, meta["cwd"]) != mapping:
return False
except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError):
return False
if policy_path:
from project_scope import load, local_active
try:
scope = load(policy_path)
if scope["consent"]["contentScope"] != "codex-session-content" or source != "codex":
return False
cutoff = local_active(scope)
except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError):
return False
state = Path(scope["stateRoot"]) if scope else home / ".local/state/hindsight-greppy"
start_file = state / "pilot-start"
if not scope and not start_file.is_file():
return False
session_id = event.get("session_id")
if not isinstance(session_id, str) or not SESSION_ID.fullmatch(session_id):
return False
try:
if not workspace_policy_path:
if source != "codex":
return False
project = (Path(scope["projectRoot"]) if scope else home / "dev/greppy").resolve(strict=True)
project_directory(event["cwd"], project)
original = Path(event["transcript_path"])
if original.is_symlink():
return False
transcript = original.resolve(strict=True)
transcript.relative_to((Path(scope["sessionsRoot"]) if scope else home / ".codex/sessions").resolve(strict=True))
meta = read_header(transcript, source)
project_directory(meta["cwd"], project)
if meta["session_id"] != session_id:
return False
started = timestamp(meta["timestamp"])
if not scope:
cutoff = datetime.datetime.fromisoformat(start_file.read_text().strip().replace("Z", "+00:00"))
if started.tzinfo is None or cutoff.tzinfo is None or started < cutoff:
return False
except (OSError, ValueError, KeyError, TypeError, json.JSONDecodeError):
return False
queue = state / "queue"
queue.mkdir(parents=True, exist_ok=True, mode=0o700)
record = {"session_id": session_id, "transcript_path": str(transcript)}
if scope:
record.update(schemaVersion=2, source=source, byte_length=meta["byte_length"],
enabled_at=cutoff.isoformat(), checkpoint_at=checkpoint_at.isoformat(),
completion_status=event.get("completion_status", "checkpoint"))
if source == "pi" and event.get("leaf_id") is not None:
if not isinstance(event["leaf_id"], str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", event["leaf_id"]):
return False
record["leaf_id"] = event["leaf_id"]
if mapping:
record["repository"] = mapping
queue_id = source + "-" + session_id if scope else session_id
if mapping:
import hashlib
queue_id = source + "-" + hashlib.sha256((mapping["repoId"] + "\n" + session_id).encode()).hexdigest()
locks = state / "locks"
locks.mkdir(exist_ok=True, mode=0o700)
fd = os.open(locks / f"{queue_id}.lock", os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
with os.fdopen(fd, "a") as lock:
os.chmod(lock.name, 0o600)
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
fd, temporary = tempfile.mkstemp(prefix=".queue-", dir=queue)
try:
with os.fdopen(fd, "w", encoding="utf-8") as stream:
json.dump(record, stream)
stream.write("\n")
os.replace(temporary, queue / f"{queue_id}.json")
finally:
if os.path.exists(temporary):
os.unlink(temporary)
return True
def main():
parser = argparse.ArgumentParser(description=__doc__)
selected = parser.add_mutually_exclusive_group()
selected.add_argument("--policy", type=Path)
selected.add_argument("--workspace-policy", type=Path)
args = parser.parse_args()
event = {}
try:
raw = sys.stdin.buffer.read(65537)
if len(raw) > 65536:
raise ValueError("hook payload bound")
event = json.loads(raw)
if not isinstance(event, dict):
raise ValueError("hook payload")
queue_session(event, Path.home(), args.policy, args.workspace_policy)
except (ValueError, OSError, TypeError, KeyError):
print("hindsight session queue failed", file=sys.stderr)
finally:
# Codex Stop expects JSON success; never request another agent turn.
if isinstance(event, dict) and event.get("hook_event_name") == "Stop":
print("{}")
if __name__ == "__main__":
main()
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 |