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.
- albert/__init__.py +3 -0
- albert/admin.py +532 -0
- albert/api.py +698 -0
- albert/automatic_memory_release.json +14 -0
- albert/benchmark.py +272 -0
- albert/benchmark_cli.py +37 -0
- albert/capture.py +1051 -0
- albert/capture_installer.py +1000 -0
- albert/capture_promotion.py +298 -0
- albert/capture_retention.py +72 -0
- albert/capture_sdk.py +558 -0
- albert/capture_security.py +79 -0
- albert/chunking.py +79 -0
- albert/classifier.py +263 -0
- albert/claude_adapter.py +357 -0
- albert/claude_lifecycle.py +418 -0
- albert/claude_package.json +19 -0
- albert/claude_plugin/.claude-plugin/plugin.json +11 -0
- albert/claude_plugin/.mcp.json +13 -0
- albert/claude_plugin/hooks/hooks.json +70 -0
- albert/clusters.py +140 -0
- albert/codex_adapter.py +308 -0
- albert/codex_hooks/hooks.json +49 -0
- albert/codex_lifecycle.py +485 -0
- albert/codex_package.json +19 -0
- albert/compatibility.py +121 -0
- albert/config.py +144 -0
- albert/console.py +508 -0
- albert/console_backends.py +236 -0
- albert/console_map.py +518 -0
- albert/console_ops.py +919 -0
- albert/credentials.py +616 -0
- albert/cursor_adapter.py +320 -0
- albert/cursor_hooks/hooks.json +11 -0
- albert/cursor_rules/albert-memory.mdc +11 -0
- albert/db.py +68 -0
- albert/embeddings.py +91 -0
- albert/graph.py +623 -0
- albert/graph_builders.py +879 -0
- albert/graph_cypher.py +669 -0
- albert/graph_store.py +376 -0
- albert/host_targets/claude-code.json +45 -0
- albert/host_targets/codex.json +45 -0
- albert/host_targets/openclaw.json +45 -0
- albert/host_targets.py +271 -0
- albert/links.py +428 -0
- albert/mcp_server.py +457 -0
- albert/memory_safety.py +111 -0
- albert/models.py +611 -0
- albert/openclaw_adapter.py +326 -0
- albert/openclaw_adapter_trust.json +5 -0
- albert/openclaw_package.json +22 -0
- albert/openclaw_plugin/index.js +135 -0
- albert/openclaw_plugin/openclaw.plugin.json +25 -0
- albert/openclaw_plugin/package.json +12 -0
- albert/portability.py +291 -0
- albert/provenance.py +105 -0
- albert/recorder.py +166 -0
- albert/release_gate.py +83 -0
- albert/schemas.py +617 -0
- albert/scope.py +26 -0
- albert/search.py +447 -0
- albert/security.py +150 -0
- albert/services.py +1316 -0
- albert/session_context.py +162 -0
- albert/trace_feed.py +165 -0
- albert/trace_writer.py +131 -0
- albert/tracing.py +75 -0
- albert/worker.py +202 -0
- albert/workspaces.py +256 -0
- albert_memory-0.4.0.dist-info/METADATA +554 -0
- albert_memory-0.4.0.dist-info/RECORD +74 -0
- albert_memory-0.4.0.dist-info/WHEEL +4 -0
- 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))
|
albert/claude_adapter.py
ADDED
|
@@ -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()
|