oliverweissl/context-garden / skills/seedbank
seedbank
VerifiedMaintain a small, generated AGENTS.md of repository facts (build commands, conventions, invariants, past mistakes) that were rediscovered often or were costly to get wrong. Use at task start to check cached facts, and at task end to log and promote what you had to dig for.
| File | Kind | Size |
|---|---|---|
| .gitignore | other | 40 B |
| SKILL.md | skill md | 2.7 KB |
| agents/gardener.md | markdown | 1.6 KB |
| bin/seedbankexecutable | script | 1.2 KB |
| references/guide.md | markdown | 3.3 KB |
| references/schema.md | markdown | 5.4 KB |
| references/scoring.md | markdown | 2.1 KB |
| scripts/cg_fingerprint.py | script | 3.1 KB |
| scripts/cg_mode.py | script | 5.4 KB |
| scripts/sb_compile.py | script | 5.6 KB |
| scripts/sb_conflicts.py | script | 2.3 KB |
| scripts/sb_hook.py | script | 13.5 KB |
| scripts/sb_scoring.py | script | 3.4 KB |
| scripts/sb_store.py | script | 9.3 KB |
| scripts/seedbank.pyexecutable | script | 43.0 KB |
| tests/fixtures/mini_repo/CMakeLists.txt | markdown | 94 B |
| tests/fixtures/mini_repo/README.md | markdown | 126 B |
| tests/fixtures/mini_repo/src/generated/bindings.cpp | other | 92 B |
| tests/fixtures/mini_repo/tools/codegen.py | script | 57 B |
| tests/smoke_test.shexecutable | script | 29.7 KB |
scripts/sb_store.py
View on GitHub"""Local storage for seedbank. Layout under the store root (.seedbank/ at the git root):
observations.jsonl append-only raw event log; `gc` may prune it (keystats holds the aggregates)
keystats.json {key: aggregate stats}, key = file path, search, command, or fact/mistake digest
facts.json {seq, facts: {fact_id: {...}}}: promoted hot/warm facts
config.json overrides of CONFIG_DEFAULTS (missing keys fall back)
nudged.json sessions the Stop hook already reminded (once per session)
.lock flock target serializing concurrent commands
.gitignore written once at creation; ignores the above, not warm/*.md
"""
from __future__ import annotations
import hashlib
import json
import os
import re
import subprocess
import tempfile
import time
from contextlib import contextmanager
from pathlib import Path
from sb_scoring import DEFAULT_FACT_FAILURE_COST, DEFAULT_HALF_LIFE_DAYS
try:
import fcntl
except ImportError: # Windows: no flock; locking degrades to a no-op
fcntl = None
DEFAULT_STORE_DIRNAME = ".seedbank"
# Written into a freshly created store: the profiler state is local, while
# warm/*.md (and AGENTS.md outside the store) are meant to be committed.
STORE_GITIGNORE = """\
# seedbank local profiler state (warm/*.md is meant to be committed)
observations.jsonl
keystats.json
facts.json
config.json
.lock
nudged.json
*.tmp
"""
DEFAULT_HOT_BUDGET = 500
DEFAULT_PROMOTE_THRESHOLD = 1.0
FAILURE_COST_RUN = 150
FAILURE_COST_MISTAKE = 300
SEARCH_DEFAULT_COST = 30
CONFIG_DEFAULTS = {
"hot_budget": DEFAULT_HOT_BUDGET,
"promote_threshold": DEFAULT_PROMOTE_THRESHOLD,
"half_life_days": DEFAULT_HALF_LIFE_DAYS,
"fact_failure_cost": DEFAULT_FACT_FAILURE_COST,
}
SESSION_ENV_VARS = ("CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")
def resolve_session(explicit: str | None = None) -> str:
"""Session id used to count *distinct sessions* per key: explicit
`--session`, else the id Claude Code exports to Bash tool calls
(CLAUDE_CODE_SESSION_ID; CLAUDE_SESSION_ID also honoured), else a
fallback of today's date + the OS session id of this terminal (stable
across the commands of one shell session; ppid if getsid is missing)."""
if explicit:
return explicit
for var in SESSION_ENV_VARS:
val = os.environ.get(var, "").strip()
if val:
return val
try:
sid = os.getsid(0)
except AttributeError: # no getsid (Windows)
sid = os.getppid()
return f"{time.strftime('%Y-%m-%d')}-{sid}"
def find_repo_root() -> Path:
"""`git rev-parse --show-toplevel`, falling back to cwd outside a git repo."""
try:
proc = subprocess.run(
["git", "rev-parse", "--show-toplevel"],
stdout=subprocess.PIPE,
stderr=subprocess.DEVNULL,
text=True,
)
if proc.returncode == 0 and proc.stdout.strip():
return Path(proc.stdout.strip()).resolve()
except FileNotFoundError: # no git binary
pass
return Path.cwd().resolve()
def find_store_root(explicit: str | None, repo_root: Path | None = None) -> Path:
if explicit:
return Path(explicit)
return (repo_root or find_repo_root()) / DEFAULT_STORE_DIRNAME
def rel_to_root(path: str, repo_root: Path) -> str:
"""Normalize a user-supplied path to repo-root-relative (posix) form so
keys/sources don't depend on the cwd the command was run from. Paths
outside the repo are kept absolute."""
p = Path(path)
if not p.is_absolute():
p = Path.cwd() / p
p = p.resolve()
try:
return p.relative_to(Path(repo_root).resolve()).as_posix()
except ValueError:
return str(p)
def safe_scope(scope: str | None) -> str:
"""Reduce a scope to a filename-safe slug (it becomes warm/<scope>.md)."""
slug = re.sub(r"[^a-z0-9_-]+", "-", (scope or "").strip().lower()).strip("-_")
return slug or "general"
def atomic_write_text(path: Path, text: str) -> None:
"""Write via temp file in the same dir + os.replace, so readers never
see a half-written file."""
path = Path(path)
try:
mode = path.stat().st_mode & 0o777
except FileNotFoundError:
mode = 0o644
fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
try:
with os.fdopen(fd, "w") as f:
f.write(text)
os.chmod(tmp, mode)
os.replace(tmp, path)
except BaseException:
try:
os.unlink(tmp)
except OSError:
pass
raise
def estimate_tokens(text: str) -> int:
"""Chars/4 rule-of-thumb token estimate. No tokenizer dependency by design."""
return max(1, round(len(text) / 4))
def sha256_file(path: str) -> str | None:
try:
data = Path(path).read_bytes()
except (FileNotFoundError, IsADirectoryError): # source deleted, or not a file
return None
return hashlib.sha256(data).hexdigest()[:16]
class Store:
def __init__(self, root: Path, repo_root: Path | None = None):
self.root = Path(root)
self.repo_root = Path(repo_root) if repo_root else self.root.resolve().parent
self.session: str | None = None # set by the CLI / hook (resolve_session)
created = not self.root.exists()
self.root.mkdir(parents=True, exist_ok=True)
if created:
try: # "x": never overwrite a .gitignore someone else put there
with (self.root / ".gitignore").open("x") as f:
f.write(STORE_GITIGNORE)
except FileExistsError:
pass
self.lock_path = self.root / ".lock"
self.obs_path = self.root / "observations.jsonl"
self.keystats_path = self.root / "keystats.json"
self.facts_path = self.root / "facts.json"
self.config_path = self.root / "config.json"
with self.lock():
if not self.keystats_path.exists():
atomic_write_text(self.keystats_path, "{}")
if not self.facts_path.exists():
atomic_write_text(self.facts_path, json.dumps({"seq": 0, "facts": {}}, indent=2))
if not self.config_path.exists():
atomic_write_text(self.config_path, json.dumps(CONFIG_DEFAULTS, indent=2))
self.obs_path.touch(exist_ok=True)
@contextmanager
def lock(self):
"""Exclusive cross-process lock; hold it across a whole
load -> modify -> save sequence. Not reentrant."""
with self.lock_path.open("a") as fh:
if fcntl is not None:
fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
try:
yield
finally:
if fcntl is not None:
fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
def source_path(self, source: str) -> Path:
"""Resolve a stored (repo-root-relative or absolute) source path."""
return self.repo_root / source
# -- keystats -----------------------------------------------------
def load_keystats(self) -> dict:
return json.loads(self.keystats_path.read_text())
def save_keystats(self, data: dict) -> None:
atomic_write_text(self.keystats_path, json.dumps(data, indent=2))
# -- facts ----------------------------------------------------------
def load_facts(self) -> dict:
return json.loads(self.facts_path.read_text())
def save_facts(self, data: dict) -> None:
atomic_write_text(self.facts_path, json.dumps(data, indent=2))
@staticmethod
def gen_fact_id(facts: dict) -> str:
"""Mutates `facts["seq"]` in place; caller must save the same dict
afterward so the increment and the new fact land in one write."""
facts["seq"] += 1
return f"f{facts['seq']:04d}"
# -- config -----------------------------------------------------------
def load_config(self) -> dict:
"""Stored overrides on top of CONFIG_DEFAULTS, so a config.json
written by an older version (no half_life_days etc.) still loads."""
return {**CONFIG_DEFAULTS, **json.loads(self.config_path.read_text())}
# -- observations -----------------------------------------------------
def append_observation(self, obs: dict) -> None:
with self.obs_path.open("a") as f:
f.write(json.dumps(obs) + "\n")
def read_observations(self) -> list[dict]:
out = []
for line in self.obs_path.read_text().splitlines():
if line.strip():
out.append(json.loads(line))
return out
def prune_observations(self, keep_per_key: int = 5) -> int:
"""Keep only the last `keep_per_key` raw observations per key.
Safe because keystats.json already holds the durable aggregates;
the raw log is only needed as an audit trail for recent activity.
Returns the number of entries removed.
"""
by_key: dict[str, list[dict]] = {}
for o in self.read_observations():
by_key.setdefault(o["key"], []).append(o)
kept = []
removed = 0
for key, obs_list in by_key.items():
removed += max(0, len(obs_list) - keep_per_key)
kept.extend(obs_list[-keep_per_key:])
kept.sort(key=lambda o: o["ts"])
atomic_write_text(self.obs_path, "".join(json.dumps(o) + "\n" for o in kept))
return removed
def now() -> float:
return time.time()
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: 472k | 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 |