albert-memory 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. albert/__init__.py +3 -0
  2. albert/admin.py +532 -0
  3. albert/api.py +698 -0
  4. albert/automatic_memory_release.json +14 -0
  5. albert/benchmark.py +272 -0
  6. albert/benchmark_cli.py +37 -0
  7. albert/capture.py +1051 -0
  8. albert/capture_installer.py +1000 -0
  9. albert/capture_promotion.py +298 -0
  10. albert/capture_retention.py +72 -0
  11. albert/capture_sdk.py +558 -0
  12. albert/capture_security.py +79 -0
  13. albert/chunking.py +79 -0
  14. albert/classifier.py +263 -0
  15. albert/claude_adapter.py +357 -0
  16. albert/claude_lifecycle.py +418 -0
  17. albert/claude_package.json +19 -0
  18. albert/claude_plugin/.claude-plugin/plugin.json +11 -0
  19. albert/claude_plugin/.mcp.json +13 -0
  20. albert/claude_plugin/hooks/hooks.json +70 -0
  21. albert/clusters.py +140 -0
  22. albert/codex_adapter.py +308 -0
  23. albert/codex_hooks/hooks.json +49 -0
  24. albert/codex_lifecycle.py +485 -0
  25. albert/codex_package.json +19 -0
  26. albert/compatibility.py +121 -0
  27. albert/config.py +144 -0
  28. albert/console.py +508 -0
  29. albert/console_backends.py +236 -0
  30. albert/console_map.py +518 -0
  31. albert/console_ops.py +919 -0
  32. albert/credentials.py +616 -0
  33. albert/cursor_adapter.py +320 -0
  34. albert/cursor_hooks/hooks.json +11 -0
  35. albert/cursor_rules/albert-memory.mdc +11 -0
  36. albert/db.py +68 -0
  37. albert/embeddings.py +91 -0
  38. albert/graph.py +623 -0
  39. albert/graph_builders.py +879 -0
  40. albert/graph_cypher.py +669 -0
  41. albert/graph_store.py +376 -0
  42. albert/host_targets/claude-code.json +45 -0
  43. albert/host_targets/codex.json +45 -0
  44. albert/host_targets/openclaw.json +45 -0
  45. albert/host_targets.py +271 -0
  46. albert/links.py +428 -0
  47. albert/mcp_server.py +457 -0
  48. albert/memory_safety.py +111 -0
  49. albert/models.py +611 -0
  50. albert/openclaw_adapter.py +326 -0
  51. albert/openclaw_adapter_trust.json +5 -0
  52. albert/openclaw_package.json +22 -0
  53. albert/openclaw_plugin/index.js +135 -0
  54. albert/openclaw_plugin/openclaw.plugin.json +25 -0
  55. albert/openclaw_plugin/package.json +12 -0
  56. albert/portability.py +291 -0
  57. albert/provenance.py +105 -0
  58. albert/recorder.py +166 -0
  59. albert/release_gate.py +83 -0
  60. albert/schemas.py +617 -0
  61. albert/scope.py +26 -0
  62. albert/search.py +447 -0
  63. albert/security.py +150 -0
  64. albert/services.py +1316 -0
  65. albert/session_context.py +162 -0
  66. albert/trace_feed.py +165 -0
  67. albert/trace_writer.py +131 -0
  68. albert/tracing.py +75 -0
  69. albert/worker.py +202 -0
  70. albert/workspaces.py +256 -0
  71. albert_memory-0.4.0.dist-info/METADATA +554 -0
  72. albert_memory-0.4.0.dist-info/RECORD +74 -0
  73. albert_memory-0.4.0.dist-info/WHEEL +4 -0
  74. albert_memory-0.4.0.dist-info/entry_points.txt +14 -0
albert/chunking.py ADDED
@@ -0,0 +1,79 @@
1
+ """Split memory text into bounded, overlapping chunks for embedding.
2
+
3
+ Embedding models truncate silently or reject long inputs, so every memory is
4
+ indexed as a sequence of chunks. Chunks follow paragraph and sentence
5
+ boundaries where possible and fall back to a hard split for unbroken runs.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+
12
+ _PARAGRAPH_BREAK = re.compile(r"\n\s*\n")
13
+ _SENTENCE_BREAK = re.compile(r"(?<=[.!?])\s+")
14
+
15
+
16
+ def _units(text: str, max_characters: int, overlap_characters: int) -> list[str]:
17
+ """Break text into pieces that each fit the budget, preferring natural breaks."""
18
+ units: list[str] = []
19
+ for paragraph in _PARAGRAPH_BREAK.split(text):
20
+ paragraph = paragraph.strip()
21
+ if not paragraph:
22
+ continue
23
+ if len(paragraph) <= max_characters:
24
+ units.append(paragraph)
25
+ continue
26
+ for sentence in _SENTENCE_BREAK.split(paragraph):
27
+ sentence = sentence.strip()
28
+ if not sentence:
29
+ continue
30
+ if len(sentence) <= max_characters:
31
+ units.append(sentence)
32
+ continue
33
+ step = max(1, max_characters - overlap_characters)
34
+ for start in range(0, len(sentence), step):
35
+ units.append(sentence[start : start + max_characters])
36
+ if start + max_characters >= len(sentence):
37
+ break
38
+ return units
39
+
40
+
41
+ def _tail(text: str, overlap_characters: int) -> str:
42
+ if overlap_characters <= 0 or len(text) <= overlap_characters:
43
+ return ""
44
+ tail = text[-overlap_characters:]
45
+ cut = tail.find(" ")
46
+ return tail[cut + 1 :].strip() if cut != -1 else tail
47
+
48
+
49
+ def chunk_text(text: str, *, max_characters: int, overlap_characters: int) -> list[str]:
50
+ """Return non-empty chunks of at most ``max_characters`` each.
51
+
52
+ Consecutive chunks share up to ``overlap_characters`` of trailing context so
53
+ a fact straddling a boundary is still embedded whole in one of them.
54
+ """
55
+ if max_characters <= 0:
56
+ raise ValueError("max_characters must be positive")
57
+ overlap_characters = max(0, min(overlap_characters, max_characters // 2))
58
+ text = text.strip()
59
+ if not text:
60
+ return []
61
+ if len(text) <= max_characters:
62
+ return [text]
63
+
64
+ chunks: list[str] = []
65
+ current = ""
66
+ for unit in _units(text, max_characters, overlap_characters):
67
+ if not current:
68
+ current = unit
69
+ continue
70
+ if len(current) + 2 + len(unit) <= max_characters:
71
+ current = f"{current}\n\n{unit}"
72
+ continue
73
+ chunks.append(current)
74
+ carry = _tail(current, overlap_characters)
75
+ fits = bool(carry) and len(carry) + 2 + len(unit) <= max_characters
76
+ current = f"{carry}\n\n{unit}" if fits else unit
77
+ if current:
78
+ chunks.append(current)
79
+ return chunks
albert/classifier.py ADDED
@@ -0,0 +1,263 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import re
5
+ from dataclasses import dataclass, field
6
+
7
+ import httpx
8
+
9
+ from albert.config import get_settings
10
+
11
+
12
+ @dataclass(frozen=True)
13
+ class ExtractedEntity:
14
+ name: str
15
+ entity_type: str = "concept"
16
+ description: str = ""
17
+ confidence: float = 0.7
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class ExtractedRelationship:
22
+ source: ExtractedEntity
23
+ relation_type: str
24
+ target: ExtractedEntity
25
+ confidence: float = 0.7
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class Classification:
30
+ memory_type: str
31
+ sensitivity: str
32
+ confidence: float
33
+ entities: list[ExtractedEntity] = field(default_factory=list)
34
+ relationships: list[ExtractedRelationship] = field(default_factory=list)
35
+
36
+
37
+ _SECRET_PATTERNS = (
38
+ re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
39
+ re.compile(r"\b(?:sk|ghp|github_pat|xox[baprs])-[_A-Za-z0-9-]{16,}\b"),
40
+ re.compile(r"\bAKIA[A-Z0-9]{16}\b"),
41
+ re.compile(r"(?i)\b(?:password|passwd|api[_ -]?key|secret)\s*[:=]\s*[^\s]{8,}"),
42
+ )
43
+
44
+
45
+ def contains_likely_secret(text: str) -> bool:
46
+ return any(pattern.search(text) for pattern in _SECRET_PATTERNS)
47
+
48
+
49
+ _RELATION_PHRASES = (
50
+ ("depends on", "depends_on"),
51
+ ("integrates with", "integrates_with"),
52
+ ("runs on", "runs_on"),
53
+ ("belongs to", "belongs_to"),
54
+ ("is owned by", "owned_by"),
55
+ ("uses", "uses"),
56
+ ("owns", "owns"),
57
+ ("manages", "manages"),
58
+ ("supports", "supports"),
59
+ ("prefers", "prefers"),
60
+ ("works on", "works_on"),
61
+ )
62
+ # An entity is one to four bare tokens. Clauses are split on punctuation and
63
+ # coordinating conjunctions first so one clause carries at most one relation and
64
+ # the captured names cannot swallow neighbouring clauses.
65
+ _ENTITY = r"((?:[\w.-]+\s+){0,3}[\w.-]+?)"
66
+ _DETERMINER = r"(?:(?:the|a|an|our|their|its)\s+)?"
67
+ _TRAILER = r"(?:\s+(?:for|to|in|on|with|as|at|by|since|because|when|via)\b.*)?"
68
+ _RELATION_PATTERNS = tuple(
69
+ (
70
+ re.compile(
71
+ rf"^{_DETERMINER}{_ENTITY}\s+{phrase}\s+{_DETERMINER}{_ENTITY}{_TRAILER}$", re.I
72
+ ),
73
+ relation_type,
74
+ )
75
+ for phrase, relation_type in _RELATION_PHRASES
76
+ )
77
+ _CLAUSE_SPLIT = re.compile(r"[.;:!?\n]+|,\s+|\s+(?:and|but|while|whereas)\s+", re.I)
78
+ _MAX_ENTITY_WORDS = 4
79
+
80
+
81
+ def _clean_entity(value: str) -> str:
82
+ value = re.sub(r"\s+", " ", value).strip(" \t\n\r,:()[]{}\"'")
83
+ words = value.split()
84
+ return " ".join(words[:_MAX_ENTITY_WORDS])[:500]
85
+
86
+
87
+ def _clauses(text: str) -> list[str]:
88
+ return [clause.strip() for clause in _CLAUSE_SPLIT.split(text) if clause and clause.strip()]
89
+
90
+
91
+ def heuristic_classify(text: str) -> Classification:
92
+ lowered = text.lower()
93
+ if any(word in lowered for word in ("must not", "danger", "warning", "avoid ")):
94
+ memory_type = "warning"
95
+ elif any(word in lowered for word in ("steps:", "procedure", "runbook", "how to")):
96
+ memory_type = "procedure"
97
+ elif any(word in lowered for word in ("decided", "decision", "we chose")):
98
+ memory_type = "decision"
99
+ elif any(word in lowered for word in ("prefers", "preference", "likes ")):
100
+ memory_type = "preference"
101
+ else:
102
+ memory_type = "fact"
103
+
104
+ relationships: list[ExtractedRelationship] = []
105
+ entities: dict[str, ExtractedEntity] = {}
106
+ for clause in _clauses(text):
107
+ for pattern, relation_type in _RELATION_PATTERNS:
108
+ match = pattern.match(clause)
109
+ if match is None:
110
+ continue
111
+ source_name, target_name = (_clean_entity(value) for value in match.groups())
112
+ if not source_name or not target_name:
113
+ continue
114
+ if source_name.casefold() == target_name.casefold():
115
+ continue
116
+ source = entities.setdefault(source_name.casefold(), ExtractedEntity(source_name))
117
+ target = entities.setdefault(target_name.casefold(), ExtractedEntity(target_name))
118
+ relationships.append(
119
+ ExtractedRelationship(source, relation_type, target, confidence=0.65)
120
+ )
121
+ break
122
+ return Classification(
123
+ memory_type=memory_type,
124
+ sensitivity="internal",
125
+ confidence=0.65,
126
+ entities=list(entities.values()),
127
+ relationships=relationships,
128
+ )
129
+
130
+
131
+ MEMORY_TYPES = (
132
+ "fact",
133
+ "preference",
134
+ "procedure",
135
+ "lesson",
136
+ "warning",
137
+ "project_state",
138
+ "task_result",
139
+ "decision",
140
+ "relationship",
141
+ "recurring_pattern",
142
+ "reminder",
143
+ "summary",
144
+ )
145
+ SENSITIVITIES = ("public", "internal", "confidential", "restricted")
146
+ MAX_ENTITIES = 40
147
+ MAX_RELATIONSHIPS = 60
148
+
149
+
150
+ def _score(value: object, default: float = 0.7) -> float:
151
+ try:
152
+ return min(1.0, max(0.0, float(value))) # type: ignore[arg-type]
153
+ except (TypeError, ValueError):
154
+ return default
155
+
156
+
157
+ def _label(value: object) -> str:
158
+ return re.sub(r"[^a-z0-9_]+", "_", str(value or "").strip().lower()).strip("_")
159
+
160
+
161
+ def _parse_model_classification(payload: dict) -> Classification:
162
+ """Validate and bound a model's reply.
163
+
164
+ A label outside the vocabulary falls back to a safe default instead of
165
+ raising: a model's wording must never be able to fail a memory's indexing.
166
+ """
167
+ memory_type = _label(payload.get("memory_type"))
168
+ if memory_type not in MEMORY_TYPES:
169
+ memory_type = "fact"
170
+ sensitivity = _label(payload.get("sensitivity"))
171
+ if sensitivity not in SENSITIVITIES:
172
+ sensitivity = "internal"
173
+
174
+ entities: dict[str, ExtractedEntity] = {}
175
+ for raw in payload.get("entities") or []:
176
+ if not isinstance(raw, dict) or len(entities) >= MAX_ENTITIES:
177
+ continue
178
+ name = _clean_entity(str(raw.get("name") or ""))
179
+ if name:
180
+ entities.setdefault(
181
+ name.casefold(),
182
+ ExtractedEntity(
183
+ name=name,
184
+ entity_type=(_label(raw.get("entity_type")) or "concept")[:100],
185
+ description=str(raw.get("description") or "")[:10_000],
186
+ confidence=_score(raw.get("confidence")),
187
+ ),
188
+ )
189
+ relationships: list[ExtractedRelationship] = []
190
+ seen: set[tuple[str, str, str]] = set()
191
+ for raw in payload.get("relationships") or []:
192
+ if not isinstance(raw, dict) or len(relationships) >= MAX_RELATIONSHIPS:
193
+ continue
194
+ source = entities.get(_clean_entity(str(raw.get("source") or "")).casefold())
195
+ target = entities.get(_clean_entity(str(raw.get("target") or "")).casefold())
196
+ relation = _label(raw.get("relation_type"))[:100]
197
+ if not (source and target and relation) or source is target:
198
+ continue
199
+ key = (source.name, relation, target.name)
200
+ if key in seen:
201
+ continue
202
+ seen.add(key)
203
+ relationships.append(
204
+ ExtractedRelationship(source, relation, target, _score(raw.get("confidence")))
205
+ )
206
+ return Classification(
207
+ memory_type=memory_type,
208
+ sensitivity=sensitivity,
209
+ confidence=_score(payload.get("confidence")),
210
+ entities=list(entities.values()),
211
+ relationships=relationships,
212
+ )
213
+
214
+
215
+ CLASSIFIER_INSTRUCTION = f"""You label one memory for an agent memory system and extract a
216
+ small knowledge graph from it. Return only a JSON object with these keys:
217
+
218
+ - memory_type: exactly one of {", ".join(MEMORY_TYPES)}.
219
+ - sensitivity: exactly one of {", ".join(SENSITIVITIES)}. Use "internal" for ordinary
220
+ working notes, plans, procedures and business detail. Use "confidential" only when the
221
+ text contains personal data about named individuals, pay, health, legal or financial
222
+ account detail. Use "restricted" only for material that would cause serious harm if
223
+ shared inside the organization. When unsure, use "internal".
224
+ - confidence: a number from 0 to 1.
225
+ - entities: at most 15 objects {{name, entity_type, description, confidence}}. Include
226
+ only specific, named things the memory is about: people, teams, roles, products,
227
+ systems, tools, files, places, organizations, recurring processes. Use the name as
228
+ written, without articles. entity_type is one lowercase word such as person, team,
229
+ role, system, tool, file, location, organization, process, product, concept.
230
+ Skip generic words, dates, numbers and one-off phrases.
231
+ - relationships: at most 20 objects {{source, relation_type, target, confidence}}.
232
+ source and target must exactly match entity names from your entities list.
233
+ relation_type is a short lowercase snake_case verb phrase such as uses, owns,
234
+ depends_on, part_of, manages, reports_to, located_at, produces, replaces, blocks.
235
+ State only relationships the text supports.
236
+
237
+ If the memory names nothing specific, return empty lists. Never include credentials or
238
+ secrets."""
239
+
240
+
241
+ def classify(text: str) -> Classification:
242
+ settings = get_settings()
243
+ if settings.llm_provider != "openai-compatible":
244
+ return heuristic_classify(text)
245
+ if settings.openai_api_key is None or not settings.classification_model:
246
+ raise ValueError("LLM classification requires an API key and classification model")
247
+ response = httpx.post(
248
+ f"{settings.openai_base_url.rstrip('/')}/chat/completions",
249
+ headers={"Authorization": f"Bearer {settings.openai_api_key.get_secret_value()}"},
250
+ json={
251
+ "model": settings.classification_model,
252
+ "temperature": 0,
253
+ "response_format": {"type": "json_object"},
254
+ "messages": [
255
+ {"role": "system", "content": CLASSIFIER_INSTRUCTION},
256
+ {"role": "user", "content": text[:100_000]},
257
+ ],
258
+ },
259
+ timeout=120,
260
+ )
261
+ response.raise_for_status()
262
+ content = response.json()["choices"][0]["message"]["content"]
263
+ return _parse_model_classification(json.loads(content))
@@ -0,0 +1,357 @@
1
+ """Native Claude Code lifecycle adapter for Albert automatic memory."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import sqlite3
9
+ import sys
10
+ import threading
11
+ from dataclasses import asdict
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ import httpx
16
+
17
+ from albert.capture_sdk import CaptureClient, DeliveryResult, EncryptedQueue, collect_vcs_context
18
+ from albert.capture_security import screen_capture
19
+
20
+ ADAPTER_VERSION = "0.1.0"
21
+ MAX_SUMMARY_CHARACTERS = 4_000
22
+ CLAUDE_EVENTS = {
23
+ "session_started",
24
+ "user_goal",
25
+ "assistant_outcome",
26
+ "pre_compaction_checkpoint",
27
+ "session_ended",
28
+ "failure_summary",
29
+ }
30
+
31
+
32
+ def _operation_key(kind: str, session: str, identity: str) -> str:
33
+ digest = hashlib.sha256(f"{kind}\0{session}\0{identity}".encode()).hexdigest()
34
+ return f"claude-code:{kind}:{digest}"
35
+
36
+
37
+ class ClaudeState:
38
+ """Crash-safe sequence allocation and hook retry deduplication."""
39
+
40
+ def __init__(self, path: str | Path) -> None:
41
+ self.path = Path(path)
42
+ self.path.parent.mkdir(parents=True, exist_ok=True)
43
+ self._lock = threading.RLock()
44
+ with self._db() as db:
45
+ db.executescript("""
46
+ CREATE TABLE IF NOT EXISTS operations (
47
+ operation_key TEXT PRIMARY KEY, session_key TEXT NOT NULL,
48
+ sequence INTEGER NOT NULL, event_class TEXT NOT NULL,
49
+ UNIQUE(session_key, sequence));
50
+ """)
51
+ os.chmod(self.path, 0o600)
52
+
53
+ def _db(self) -> sqlite3.Connection:
54
+ db = sqlite3.connect(self.path, timeout=10)
55
+ db.execute("PRAGMA journal_mode=WAL")
56
+ db.execute("PRAGMA synchronous=FULL")
57
+ return db
58
+
59
+ def sequence(self, session: str, operation_key: str, event_class: str) -> int:
60
+ with self._lock, self._db() as db:
61
+ db.execute("BEGIN IMMEDIATE")
62
+ existing = db.execute(
63
+ "SELECT sequence FROM operations WHERE operation_key=?", (operation_key,)
64
+ ).fetchone()
65
+ if existing:
66
+ return int(existing[0])
67
+ row = db.execute(
68
+ "SELECT coalesce(max(sequence),0) FROM operations WHERE session_key=?", (session,)
69
+ ).fetchone()
70
+ sequence = int(row[0]) + 1
71
+ db.execute(
72
+ "INSERT INTO operations VALUES(?,?,?,?)",
73
+ (operation_key, session, sequence, event_class),
74
+ )
75
+ return sequence
76
+
77
+ def final_sequence(self, session: str) -> int:
78
+ with self._lock, self._db() as db:
79
+ row = db.execute(
80
+ "SELECT coalesce(max(sequence),0) FROM operations WHERE session_key=?", (session,)
81
+ ).fetchone()
82
+ return int(row[0])
83
+
84
+
85
+ class ClaudeAdapter:
86
+ """Maps supported Claude Code hooks onto the shared capture SDK contract."""
87
+
88
+ def __init__(
89
+ self,
90
+ client: CaptureClient,
91
+ state: ClaudeState,
92
+ *,
93
+ workspace_id: str | None = None,
94
+ ) -> None:
95
+ self.client = client
96
+ self.state = state
97
+ self.workspace_id = workspace_id
98
+
99
+ @staticmethod
100
+ def _session(event: dict[str, Any]) -> str:
101
+ value = event.get("session_id")
102
+ if not isinstance(value, str) or not value.strip():
103
+ raise ValueError("Claude Code hook requires session_id")
104
+ return value[:300]
105
+
106
+ @staticmethod
107
+ def _vcs(event: dict[str, Any]) -> dict[str, Any]:
108
+ cwd = event.get("cwd")
109
+ if not isinstance(cwd, str) or not cwd:
110
+ return {"vcs": "none", "project": "unknown", "include_absolute_path": False}
111
+ return collect_vcs_context(cwd)
112
+
113
+ @classmethod
114
+ def _provenance(cls, event: dict[str, Any], hook: str) -> dict[str, Any]:
115
+ vcs = cls._vcs(event)
116
+ return {
117
+ "client": "claude-code",
118
+ "agent": str(event.get("agent_type", "main"))[:200],
119
+ "project": str(vcs.get("project", "unknown"))[:300],
120
+ "branch": str(vcs.get("branch") or vcs.get("ref") or "")[:300] or None,
121
+ "run": str(event.get("prompt_id", ""))[:300] or None,
122
+ "event": hook[:300],
123
+ "source_session": cls._session(event),
124
+ "adapter_version": ADAPTER_VERSION,
125
+ "include_absolute_path": False,
126
+ }
127
+
128
+ @classmethod
129
+ def _capture_session(cls, event: dict[str, Any]) -> str:
130
+ session = cls._session(event)
131
+ return _operation_key("start", session, session)
132
+
133
+ def _start(self, event: dict[str, Any]) -> DeliveryResult:
134
+ session = self._session(event)
135
+ return self.client.start_session(
136
+ session,
137
+ self._capture_session(event),
138
+ workspace_id=self.workspace_id,
139
+ provenance=self._provenance(event, "SessionStart"),
140
+ )
141
+
142
+ def _record(
143
+ self,
144
+ event: dict[str, Any],
145
+ event_class: str,
146
+ content: str,
147
+ identity: str,
148
+ hook: str,
149
+ ) -> DeliveryResult:
150
+ screened = screen_capture(content[:MAX_SUMMARY_CHARACTERS], {})
151
+ if screened.reasons:
152
+ return DeliveryResult("dropped", "secret_detected")
153
+ capture_session = self._capture_session(event)
154
+ key = _operation_key(event_class, capture_session, identity)
155
+ sequence = self.state.sequence(capture_session, key, event_class)
156
+ return self.client.record_event(
157
+ capture_session,
158
+ sequence,
159
+ event_class,
160
+ screened.content,
161
+ key,
162
+ provenance=self._provenance(event, hook),
163
+ )
164
+
165
+ def handle(self, event: dict[str, Any]) -> dict[str, Any]:
166
+ hook = str(event.get("hook_event_name", ""))
167
+ if hook not in {
168
+ "SessionStart",
169
+ "UserPromptSubmit",
170
+ "PreCompact",
171
+ "Stop",
172
+ "StopFailure",
173
+ "SessionEnd",
174
+ }:
175
+ raise ValueError(f"unsupported Claude Code hook: {hook}")
176
+
177
+ self.client.flush()
178
+ results: list[DeliveryResult] = [self._start(event)]
179
+ session = self._session(event)
180
+ capture_session = self._capture_session(event)
181
+
182
+ if hook == "SessionStart":
183
+ source = str(event.get("source", "startup"))[:100]
184
+ results.append(
185
+ self._record(
186
+ event,
187
+ "session_started",
188
+ f"Claude Code session started: {source}.",
189
+ f"{session}:{source}",
190
+ hook,
191
+ )
192
+ )
193
+ project = self._vcs(event).get("project")
194
+ query = f"Approved project context for {project or 'this Claude Code workspace'}"
195
+ context = self.client.recall(query, provenance=self._provenance(event, hook))
196
+ return {
197
+ "hookSpecificOutput": {
198
+ "hookEventName": "SessionStart",
199
+ "additionalContext": context,
200
+ },
201
+ "results": [asdict(item) for item in results],
202
+ }
203
+
204
+ if hook == "UserPromptSubmit":
205
+ prompt = str(event.get("prompt", ""))[:MAX_SUMMARY_CHARACTERS]
206
+ screened = screen_capture(prompt, {})
207
+ if not prompt.strip() or screened.reasons:
208
+ return {"results": [asdict(item) for item in results]}
209
+ identity = str(event.get("prompt_id") or hashlib.sha256(prompt.encode()).hexdigest())
210
+ results.append(self._record(event, "user_goal", prompt, identity, hook))
211
+ context = self.client.recall(
212
+ screened.content, provenance=self._provenance(event, hook)
213
+ )
214
+ return {
215
+ "hookSpecificOutput": {
216
+ "hookEventName": "UserPromptSubmit",
217
+ "additionalContext": context,
218
+ },
219
+ "results": [asdict(item) for item in results],
220
+ }
221
+ if hook == "PreCompact":
222
+ trigger = str(event.get("trigger", "unknown"))[:100]
223
+ identity = str(event.get("prompt_id") or f"{trigger}:compaction")
224
+ results.append(
225
+ self._record(
226
+ event,
227
+ "pre_compaction_checkpoint",
228
+ f"Claude Code pre-compaction checkpoint: {trigger}.",
229
+ identity,
230
+ hook,
231
+ )
232
+ )
233
+ results.append(
234
+ self.client.checkpoint(
235
+ capture_session,
236
+ self.state.final_sequence(capture_session),
237
+ _operation_key("checkpoint", session, identity),
238
+ )
239
+ )
240
+ elif hook == "Stop":
241
+ content = str(event.get("last_assistant_message") or "Claude Code turn completed.")
242
+ identity = str(
243
+ event.get("prompt_id")
244
+ or hashlib.sha256(content[:MAX_SUMMARY_CHARACTERS].encode()).hexdigest()
245
+ )
246
+ results.append(self._record(event, "assistant_outcome", content, identity, hook))
247
+ elif hook == "StopFailure":
248
+ error = str(event.get("error", "unknown"))[:100]
249
+ identity = str(event.get("prompt_id") or error)
250
+ results.append(
251
+ self._record(
252
+ event,
253
+ "failure_summary",
254
+ f"Claude Code turn failed: {error}.",
255
+ identity,
256
+ hook,
257
+ )
258
+ )
259
+ elif hook == "SessionEnd":
260
+ reason = str(event.get("reason", "other"))[:100]
261
+ results.append(
262
+ self._record(
263
+ event,
264
+ "session_ended",
265
+ f"Claude Code session ended: {reason}.",
266
+ session,
267
+ hook,
268
+ )
269
+ )
270
+ sequence = self.state.final_sequence(capture_session)
271
+ results.append(
272
+ self.client.checkpoint(
273
+ capture_session,
274
+ sequence,
275
+ _operation_key("end-checkpoint", session, session),
276
+ )
277
+ )
278
+ results.append(
279
+ self.client.end_session(
280
+ capture_session,
281
+ sequence,
282
+ _operation_key("end", session, session),
283
+ )
284
+ )
285
+
286
+ return {"results": [asdict(item) for item in results]}
287
+
288
+
289
+ def _client_from_environment() -> tuple[CaptureClient, ClaudeState, str | None]:
290
+ environment = dict(os.environ)
291
+ credential_file = environment.get("ALBERT_CAPTURE_CREDENTIAL_FILE")
292
+ if credential_file:
293
+ path = Path(credential_file)
294
+ metadata = path.lstat()
295
+ if path.is_symlink() or not path.is_file():
296
+ raise RuntimeError("Albert credential file must be a regular file")
297
+ if metadata.st_uid != os.geteuid() or metadata.st_mode & 0o077:
298
+ raise RuntimeError("Albert credential file ownership or permissions are unsafe")
299
+ values = json.loads(path.read_text(encoding="utf-8"))
300
+ if not isinstance(values, dict) or not all(
301
+ isinstance(key, str) and isinstance(value, str) for key, value in values.items()
302
+ ):
303
+ raise RuntimeError("Albert credential file is invalid")
304
+ environment.update(values)
305
+ base_url = environment.get("ALBERT_API_URL", "http://127.0.0.1:8080")
306
+ token = environment.get("ALBERT_CAPTURE_TOKEN")
307
+ queue_key = environment.get("ALBERT_CAPTURE_QUEUE_KEY")
308
+ if not token or not queue_key:
309
+ raise RuntimeError("ALBERT_CAPTURE_TOKEN and ALBERT_CAPTURE_QUEUE_KEY are required")
310
+ queue_path = Path(
311
+ environment.get("ALBERT_CAPTURE_QUEUE_PATH", "~/.claude/albert/capture.db")
312
+ ).expanduser()
313
+ scope = environment.get("ALBERT_CAPTURE_SCOPE", "claude-code:default")
314
+ timeout = max(0.1, min(5.0, float(environment.get("ALBERT_CAPTURE_TIMEOUT", "1.0"))))
315
+ queue = EncryptedQueue(queue_path, queue_key, scope)
316
+ http = httpx.Client(
317
+ base_url=base_url.rstrip("/"),
318
+ headers={"Authorization": f"Bearer {token}"},
319
+ timeout=timeout,
320
+ )
321
+ client = CaptureClient(
322
+ base_url,
323
+ token,
324
+ queue,
325
+ local_event_classes=CLAUDE_EVENTS,
326
+ client=http,
327
+ )
328
+ return (
329
+ client,
330
+ ClaudeState(queue_path.with_suffix(".claude-state.db")),
331
+ environment.get("ALBERT_WORKSPACE_ID"),
332
+ )
333
+
334
+
335
+ def main() -> None:
336
+ """Process one minimized Claude Code hook envelope from stdin, always fail open."""
337
+ client: CaptureClient | None = None
338
+ try:
339
+ value = json.load(sys.stdin)
340
+ if not isinstance(value, dict):
341
+ raise ValueError("hook envelope must be an object")
342
+ client, state, workspace_id = _client_from_environment()
343
+ adapter = ClaudeAdapter(client, state, workspace_id=workspace_id)
344
+ print(json.dumps(adapter.handle(value), separators=(",", ":")))
345
+ except Exception as exc:
346
+ print(
347
+ json.dumps({"albert_status": "unavailable", "error": type(exc).__name__}),
348
+ file=sys.stderr,
349
+ )
350
+ print("{}")
351
+ finally:
352
+ if client is not None:
353
+ client.close()
354
+
355
+
356
+ if __name__ == "__main__":
357
+ main()