Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(hooks): preserve extension event metadata

AkitaOnRails72d5c7cfc1ac
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 81fa1214..ffcc0246 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `ai-memory bootstrap` now prunes collected sources before POSTing to the
server and supports `--chunk-input-tokens` to process large repositories via
sequential LLM calls instead of one oversized prompt.
+- Opt-in extension event metadata for `/hook`: custom integrations can
+ pass `extension=<namespace>` (and optionally `source_event=<name>`) to
+ preserve a validated third-party source event while storage keeps the
+ canonical `ObservationKind` closed. Unknown events without an extension
+ still collapse to `other` with no source-event metadata.
- `.ai-memory.toml` marker file lets a directory tree declare its
`workspace` (required) and `project` (optional) without depending on
`basename($cwd)`. Lifecycle hook scripts walk up from `cwd` to find
diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rs
index 688b44b8..42cba6e4 100644
--- a/crates/ai-memory-consolidate/src/consolidator.rs
+++ b/crates/ai-memory-consolidate/src/consolidator.rs
@@ -363,7 +363,11 @@ pub fn build_batch_request(session_id: SessionId, observations: &[Observation])
buf.push_str(&session_id.to_string());
buf.push_str("\n\nObservations:\n");
for o in observations {
- buf.push_str(&format!("- {} | {}\n", o.kind.as_str(), one_line(&o.title)));
+ buf.push_str(&format!(
+ "- {} | {}\n",
+ observation_label(o),
+ one_line(&o.title)
+ ));
if !o.body.trim().is_empty() {
buf.push_str(&format!(" body: {}\n", one_line(&o.body)));
}
@@ -441,7 +445,11 @@ fn build_request(
buf.push_str(&session_id.to_string());
buf.push_str("\nObservations (in order):\n\n");
for o in observations {
- buf.push_str(&format!("- {} | {}\n", o.kind.as_str(), one_line(&o.title)));
+ buf.push_str(&format!(
+ "- {} | {}\n",
+ observation_label(o),
+ one_line(&o.title)
+ ));
if !o.body.trim().is_empty() {
buf.push_str(&format!(" body: {}\n", one_line(&o.body)));
}
@@ -471,6 +479,15 @@ fn build_request(
}
}
+fn observation_label(obs: &Observation) -> String {
+ match (&obs.extension, &obs.source_event) {
+ (Some(extension), Some(source_event)) => {
+ format!("{} [{}:{}]", obs.kind.as_str(), extension, source_event)
+ }
+ _ => obs.kind.as_str().to_string(),
+ }
+}
+
fn build_frontmatter(page: &ConsolidatedPage) -> serde_json::Value {
let mut map = serde_json::Map::new();
map.insert(
diff --git a/crates/ai-memory-consolidate/tests/recall_eval.rs b/crates/ai-memory-consolidate/tests/recall_eval.rs
index f98b6159..518614bc 100644
--- a/crates/ai-memory-consolidate/tests/recall_eval.rs
+++ b/crates/ai-memory-consolidate/tests/recall_eval.rs
@@ -273,6 +273,8 @@ async fn raw_observation_fallback_recovers_detail_when_wiki_misses() {
workspace_id: ws,
project_id: proj,
kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
title: "raw prompt".into(),
body: "raw fallback detail mentions capybara exactly once".into(),
importance: 5,
diff --git a/crates/ai-memory-core/src/observation.rs b/crates/ai-memory-core/src/observation.rs
index aeda8dbe..c8775e35 100644
--- a/crates/ai-memory-core/src/observation.rs
+++ b/crates/ai-memory-core/src/observation.rs
@@ -87,6 +87,15 @@ pub struct NewObservation {
pub project_id: ProjectId,
/// Event classification.
pub kind: ObservationKind,
+ /// Optional third-party extension namespace that supplied
+ /// `source_event`. Core ai-memory event routing does not use
+ /// this; it preserves custom vocabularies without expanding
+ /// [`ObservationKind`].
+ pub extension: Option<String>,
+ /// Optional source event name from an opt-in extension vocabulary.
+ /// Unknown hook events leave this unset unless the hook explicitly
+ /// declared an extension namespace.
+ pub source_event: Option<String>,
/// Short title (auto-derived from event when blank).
pub title: String,
/// Sanitised body (may include excerpts of prompts or tool I/O).
@@ -108,6 +117,10 @@ pub struct Observation {
pub project_id: ProjectId,
/// Event classification.
pub kind: ObservationKind,
+ /// Optional third-party extension namespace.
+ pub extension: Option<String>,
+ /// Optional source event name from an opt-in extension vocabulary.
+ pub source_event: Option<String>,
/// Short title.
pub title: String,
/// Sanitised body.
diff --git a/crates/ai-memory-core/src/sanitize.rs b/crates/ai-memory-core/src/sanitize.rs
index 62ce964a..fc2c21a4 100644
--- a/crates/ai-memory-core/src/sanitize.rs
+++ b/crates/ai-memory-core/src/sanitize.rs
@@ -282,6 +282,8 @@ mod tests {
workspace_id: WorkspaceId::new(),
project_id: ProjectId::new(),
kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
title: "OPENAI_API_KEY=sk-leak-1234567890abcdef".into(),
body: "see /home/user/.ssh/id_ed25519".into(),
importance: 5,
diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rs
index 56c9c75f..785f73bb 100644
--- a/crates/ai-memory-hooks/src/payload.rs
+++ b/crates/ai-memory-hooks/src/payload.rs
@@ -22,6 +22,14 @@ pub struct HookQuery {
/// Project name override (same source as `workspace`). When
/// `None` the server falls back to `basename(cwd)`.
pub project: Option<String>,
+ /// Optional third-party extension namespace. When present, ai-memory
+ /// preserves a validated source event name without expanding the
+ /// closed core event vocabulary.
+ pub extension: Option<String>,
+ /// Optional explicit source event name for extension vocabularies.
+ /// When omitted and `extension` is present, unknown `event` values
+ /// are preserved as the source event.
+ pub source_event: Option<String>,
}
/// Coalesced view of an incoming hook event after light parsing of the
@@ -44,6 +52,10 @@ pub struct HookEnvelope {
/// Project name override declared by the hook. Empty / `None`
/// defers to `basename(cwd)`.
pub project_override: Option<String>,
+ /// Optional third-party extension namespace.
+ pub extension: Option<String>,
+ /// Optional source event name from the extension vocabulary.
+ pub source_event: Option<String>,
/// Optional title hint extracted from the body.
pub title_hint: Option<String>,
/// Optional body excerpt extracted from the agent's raw payload.
@@ -177,8 +189,29 @@ impl HookEnvelope {
let cwd = body_cwd.or_else(|| query.cwd.filter(|s| !s.is_empty()));
let workspace_override = query.workspace.filter(|s| !s.is_empty());
let project_override = query.project.filter(|s| !s.is_empty());
- let title_hint = best_title_hint(event, &raw);
- let body_excerpt = best_body_excerpt(event, &raw);
+ let extension = normalize_extension_name(query.extension.as_deref());
+ let source_event = extension.as_ref().and_then(|_| {
+ let raw_source = query
+ .source_event
+ .as_deref()
+ .or_else(|| (event == HookEvent::Other).then_some(query.event.as_str()))?;
+ normalize_source_event(raw_source)
+ });
+ let extension = if source_event.is_some() {
+ extension
+ } else {
+ None
+ };
+ let title_hint = best_title_hint(event, &raw).or_else(|| {
+ source_event
+ .as_deref()
+ .map(|source| extension_title_hint(&raw, source))
+ });
+ let body_excerpt = best_body_excerpt(event, &raw).or_else(|| {
+ source_event
+ .as_deref()
+ .and_then(|_| extension_body_excerpt(&raw))
+ });
Self {
event,
agent,
@@ -186,6 +219,8 @@ impl HookEnvelope {
cwd,
workspace_override,
project_override,
+ extension,
+ source_event,
title_hint,
body_excerpt,
raw,
@@ -269,6 +304,27 @@ fn best_title_hint(event: HookEvent, raw: &serde_json::Value) -> Option<String>
}
}
+fn extension_title_hint(raw: &serde_json::Value, source_event: &str) -> String {
+ extract_string(raw, &["title", "summary", "subject", "name"])
+ .map(|s| truncate_for_title(&s))
+ .unwrap_or_else(|| source_event.to_string())
+}
+
+fn extension_body_excerpt(raw: &serde_json::Value) -> Option<String> {
+ extract_string(
+ raw,
+ &[
+ "body",
+ "message",
+ "text",
+ "description",
+ "summary",
+ "details",
+ ],
+ )
+ .map(|s| truncate_excerpt(&s))
+}
+
fn best_body_excerpt(event: HookEvent, raw: &serde_json::Value) -> Option<String> {
match event {
HookEvent::UserPrompt => extract_string(raw, &["prompt", "message", "text"]),
@@ -315,6 +371,29 @@ fn truncate_excerpt(s: &str) -> String {
}
}
+fn normalize_extension_name(value: Option<&str>) -> Option<String> {
+ normalize_token(value?, 64)
+}
+
+fn normalize_source_event(value: &str) -> Option<String> {
+ normalize_token(value, 128)
+}
+
+fn normalize_token(value: &str, max_len: usize) -> Option<String> {
+ let trimmed = value.trim();
+ if trimmed.is_empty() || trimmed.len() > max_len {
+ return None;
+ }
+ if trimmed
+ .chars()
+ .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-' | ':'))
+ {
+ Some(trimmed.to_string())
+ } else {
+ None
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -327,6 +406,67 @@ mod tests {
assert_eq!(HookEvent::parse("bogus"), HookEvent::Other);
}
+ #[test]
+ fn extension_event_preserves_source_event_when_opted_in() {
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "lead.contact".into(),
+ extension: Some("fstech".into()),
+ ..Default::default()
+ },
+ serde_json::json!({
+ "session_id": "fst-1",
+ "title": "Lead contacted",
+ "message": "Lead Maria requested a proposal"
+ }),
+ );
+
+ assert_eq!(env.event, HookEvent::Other);
+ assert_eq!(env.extension.as_deref(), Some("fstech"));
+ assert_eq!(env.source_event.as_deref(), Some("lead.contact"));
+ assert_eq!(env.title_hint.as_deref(), Some("Lead contacted"));
+ assert_eq!(
+ env.body_excerpt.as_deref(),
+ Some("Lead Maria requested a proposal")
+ );
+ }
+
+ #[test]
+ fn unknown_event_without_extension_leaves_no_source_event() {
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "lead.contact".into(),
+ ..Default::default()
+ },
+ serde_json::json!({
+ "session_id": "fst-1",
+ "title": "Lead contacted",
+ "message": "Lead Maria requested a proposal"
+ }),
+ );
+
+ assert_eq!(env.event, HookEvent::Other);
+ assert_eq!(env.extension, None);
+ assert_eq!(env.source_event, None);
+ assert_eq!(env.title_hint, None);
+ assert_eq!(env.body_excerpt, None);
+ }
+
+ #[test]
+ fn invalid_extension_tokens_are_not_preserved() {
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "lead.contact".into(),
+ extension: Some("bad extension".into()),
+ ..Default::default()
+ },
+ serde_json::json!({ "session_id": "fst-1" }),
+ );
+
+ assert_eq!(env.extension, None);
+ assert_eq!(env.source_event, None);
+ }
+
#[test]
fn maps_to_observation_kind() {
assert_eq!(
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 191566bf..be312cab 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -374,6 +374,8 @@ async fn process(state: &HookState, env: HookEnvelope) -> anyhow::Result<()> {
workspace_id: ws,
project_id: proj,
kind,
+ extension: env.extension.clone(),
+ source_event: env.source_event.clone(),
title,
body,
importance: importance_for(env.event),
@@ -866,6 +868,94 @@ mod tests {
assert_eq!(counts.observations, 1);
}
+ #[tokio::test]
+ async fn process_preserves_opt_in_extension_event_metadata() {
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "lead.contact".into(),
+ agent: Some("other".into()),
+ extension: Some("fstech".into()),
+ ..Default::default()
+ },
+ serde_json::json!({
+ "session_id": "fstech-custom-event",
+ "cwd": "/home/user/crm",
+ "title": "Lead contacted",
+ "message": "Lead Maria requested a proposal"
+ }),
+ );
+ let session_id = resolve_session_id(&env).unwrap();
+
+ process(&state, env).await.unwrap();
+
+ let observations = state
+ .reader
+ .observations_for_session(session_id)
+ .await
+ .unwrap();
+ assert_eq!(observations.len(), 1);
+ let obs = &observations[0];
+ assert_eq!(obs.kind, ObservationKind::Other);
+ assert_eq!(obs.extension.as_deref(), Some("fstech"));
+ assert_eq!(obs.source_event.as_deref(), Some("lead.contact"));
+ assert_eq!(obs.title, "Lead contacted");
+ assert_eq!(obs.body, "Lead Maria requested a proposal");
+ let hits = state
+ .reader
+ .search_observations_for_project(obs.workspace_id, obs.project_id, "maria".into(), 5)
+ .await
+ .unwrap();
+ assert_eq!(hits.len(), 1, "extension body should be searchable");
+ }
+
+ #[tokio::test]
+ async fn process_unknown_event_without_extension_leaves_storage_clean() {
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "lead.contact".into(),
+ agent: Some("other".into()),
+ ..Default::default()
+ },
+ serde_json::json!({
+ "session_id": "plain-unknown-event",
+ "cwd": "/home/user/crm",
+ "title": "Lead contacted",
+ "message": "Lead Maria requested a proposal"
+ }),
+ );
+ let session_id = resolve_session_id(&env).unwrap();
+
+ process(&state, env).await.unwrap();
+
+ let observations = state
+ .reader
+ .observations_for_session(session_id)
+ .await
+ .unwrap();
+ assert_eq!(observations.len(), 1);
+ let obs = &observations[0];
+ assert_eq!(obs.kind, ObservationKind::Other);
+ assert_eq!(obs.extension, None);
+ assert_eq!(obs.source_event, None);
+ assert_eq!(obs.title, "other");
+ assert!(obs.body.is_empty());
+ let hits = state
+ .reader
+ .search_observations_for_project(obs.workspace_id, obs.project_id, "maria".into(), 5)
+ .await
+ .unwrap();
+ assert!(
+ hits.is_empty(),
+ "unknown events without extension must not leak custom payload into observation FTS"
+ );
+ }
+
/// `.ai-memory.toml` walk-up declares `workspace = "movvia"`. The hook
/// forwards it as a query param, so the same `cwd` ends up in a
/// distinct workspace from the default-buckets resolver path.
diff --git a/crates/ai-memory-hooks/src/synth.rs b/crates/ai-memory-hooks/src/synth.rs
index 66d09575..2c85a715 100644
--- a/crates/ai-memory-hooks/src/synth.rs
+++ b/crates/ai-memory-hooks/src/synth.rs
@@ -108,9 +108,10 @@ fn render_body(session_id: SessionId, observations: &[Observation], title: &str)
buf.push_str("## Raw observations\n\n");
for obs in observations {
+ let kind = observation_kind_label(obs);
buf.push_str(&format!(
"- `{}` @ {} — {}\n",
- obs.kind.as_str(),
+ kind,
human_ts(&obs.created_at),
obs.title.chars().take(80).collect::<String>(),
));
@@ -120,6 +121,15 @@ fn render_body(session_id: SessionId, observations: &[Observation], title: &str)
buf
}
+fn observation_kind_label(obs: &Observation) -> String {
+ match (&obs.extension, &obs.source_event) {
+ (Some(extension), Some(source_event)) => {
+ format!("{} [{}:{}]", obs.kind.as_str(), extension, source_event)
+ }
+ _ => obs.kind.as_str().to_string(),
+ }
+}
+
fn human_ts(ts: &jiff::Timestamp) -> String {
ts.to_zoned(TimeZone::UTC)
.strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -139,6 +149,8 @@ mod tests {
workspace_id: WorkspaceId::new(),
project_id: ProjectId::new(),
kind,
+ extension: None,
+ source_event: None,
title: title.into(),
body: String::new(),
importance: 5,
@@ -182,4 +194,20 @@ mod tests {
assert!(page.body.contains("`Bash`: 1"));
assert!(page.body.contains("build the thing"));
}
+
+ #[test]
+ fn body_includes_opt_in_extension_source_event() {
+ let mut custom = obs(ObservationKind::Other, "Lead contacted");
+ custom.extension = Some("fstech".into());
+ custom.source_event = Some("lead.contact".into());
+
+ let page = synthesize_session_page(
+ WorkspaceId::new(),
+ ProjectId::new(),
+ SessionId::new(),
+ &[custom],
+ );
+
+ assert!(page.body.contains("`other [fstech:lead.contact]`"));
+ }
}
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index f54c942c..0a3ba2f7 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -1088,6 +1088,8 @@ mod tests {
workspace_id: ws,
project_id: proj,
kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
title: "raw prompt".into(),
body: "raw fallback contains quokka only detail".into(),
importance: 5,
diff --git a/crates/ai-memory-mcp/tests/admin_phase3.rs b/crates/ai-memory-mcp/tests/admin_phase3.rs
index 01a97b0e..1dcebfcd 100644
--- a/crates/ai-memory-mcp/tests/admin_phase3.rs
+++ b/crates/ai-memory-mcp/tests/admin_phase3.rs
@@ -98,6 +98,8 @@ async fn seed_sessions_for_reorg(store: &Store) -> (SessionId, SessionId) {
workspace_id: ws,
project_id: scratch,
kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
title: "alpha prompt".into(),
body: "".into(),
importance: 5,
@@ -124,6 +126,8 @@ async fn seed_sessions_for_reorg(store: &Store) -> (SessionId, SessionId) {
workspace_id: ws,
project_id: scratch,
kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
title: "beta prompt".into(),
body: "".into(),
importance: 5,
diff --git a/crates/ai-memory-mcp/tests/admin_purge.rs b/crates/ai-memory-mcp/tests/admin_purge.rs
index 1cdbeb86..2db54f8d 100644
--- a/crates/ai-memory-mcp/tests/admin_purge.rs
+++ b/crates/ai-memory-mcp/tests/admin_purge.rs
@@ -127,6 +127,8 @@ async fn seed_two_projects(store: &Store, wiki: &Wiki) -> (WorkspaceId, ProjectI
workspace_id: ws,
project_id: proj,
kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
title: format!("{label} obs {i}"),
body: "body".into(),
importance: 5,
diff --git a/crates/ai-memory-store/migrations/V10__observation_extension_events.sql b/crates/ai-memory-store/migrations/V10__observation_extension_events.sql
new file mode 100644
index 00000000..3d44072f
--- /dev/null
+++ b/crates/ai-memory-store/migrations/V10__observation_extension_events.sql
@@ -0,0 +1,13 @@
+-- Optional third-party event metadata.
+--
+-- Core observation.kind remains the closed ai-memory lifecycle enum. These
+-- nullable fields preserve an opt-in extension namespace + source event name
+-- for custom event vocabularies without letting unknown hook event names sprawl
+-- into the canonical kind column.
+
+ALTER TABLE observations ADD COLUMN extension TEXT;
+ALTER TABLE observations ADD COLUMN source_event TEXT;
+
+CREATE INDEX idx_observations_extension_event
+ ON observations(workspace_id, project_id, extension, source_event, created_at)
+ WHERE extension IS NOT NULL AND source_event IS NOT NULL;
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index e5e63c25..7b21a80d 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -555,6 +555,8 @@ mod tests {
workspace_id: ws,
project_id: proj,
kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
title: "prompt".into(),
body: "the raw-only zebra detail lives here".into(),
importance: 5,
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index 3c24e59f..133b3d8b 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -384,16 +384,25 @@ pub fn insert_observation(
let now = Timestamp::now().as_microsecond();
let kind = observation_kind_as_str(obs.kind);
let importance: i64 = i64::from(obs.importance.clamp(1, 10));
+ let (extension, source_event) = match (&obs.extension, &obs.source_event) {
+ (Some(extension), Some(source_event)) => {
+ (Some(extension.as_str()), Some(source_event.as_str()))
+ }
+ _ => (None, None),
+ };
conn.execute(
"INSERT INTO observations \
- (id, session_id, workspace_id, project_id, kind, title, body, importance, created_at) \
- VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
+ (id, session_id, workspace_id, project_id, kind, extension, source_event, title, body, \
+ importance, created_at) \
+ VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
params![
id.as_bytes(),
obs.session_id.as_bytes(),
obs.workspace_id.as_bytes(),
obs.project_id.as_bytes(),
kind,
+ extension,
+ source_event,
obs.title,
obs.body,
importance,
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index afa55bae..2ad66444 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -646,8 +646,8 @@ impl ReaderPool {
) -> StoreResult<Vec<Observation>> {
self.with_conn(move |conn| {
let mut stmt = conn.prepare_cached(
- "SELECT id, session_id, workspace_id, project_id, kind, title, body, \
- importance, created_at \
+ "SELECT id, session_id, workspace_id, project_id, kind, extension, source_event, \
+ title, body, importance, created_at \
FROM observations \
WHERE session_id = ?1 \
ORDER BY created_at ASC",
@@ -1905,16 +1905,20 @@ fn row_to_observation(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<O
let workspace_bytes: Vec<u8> = row.get(2)?;
let project_bytes: Vec<u8> = row.get(3)?;
let kind_str: String = row.get(4)?;
- let title: String = row.get(5)?;
- let body: String = row.get(6)?;
- let importance: i64 = row.get(7)?;
- let created_us: i64 = row.get(8)?;
+ let extension: Option<String> = row.get(5)?;
+ let source_event: Option<String> = row.get(6)?;
+ let title: String = row.get(7)?;
+ let body: String = row.get(8)?;
+ let importance: i64 = row.get(9)?;
+ let created_us: i64 = row.get(10)?;
Ok(materialise_observation(
id_bytes,
session_bytes,
workspace_bytes,
project_bytes,
kind_str,
+ extension,
+ source_event,
title,
body,
importance,
@@ -1929,6 +1933,8 @@ fn materialise_observation(
workspace_bytes: Vec<u8>,
project_bytes: Vec<u8>,
kind_str: String,
+ extension: Option<String>,
+ source_event: Option<String>,
title: String,
body: String,
importance: i64,
@@ -1942,6 +1948,8 @@ fn materialise_observation(
kind: kind_str
.parse::<ObservationKind>()
.map_err(StoreError::from)?,
+ extension,
+ source_event,
title,
body,
#[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 46e3f694..8968b6b3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -101,6 +101,35 @@ markdown stays the source of truth.
backup API so the source stays writable; `ai-memory restore`
reverses. Or: `git push` the wiki dir + `rsync` the data dir.
+## Hook event vocabulary
+
+The core observation vocabulary is a closed set of agent lifecycle
+events. Hook bridges may accept client-specific aliases, but storage
+normalises them to exactly one of these `ObservationKind` values:
+
+| Stored kind | Semantics |
+|---|---|
+| `session-start` | Agent session began; cwd/model/session identity captured. |
+| `user-prompt` | User submitted prompt text to the agent. |
+| `pre-tool-use` | Agent is about to call a tool. |
+| `post-tool-use` | Agent finished a tool call. |
+| `pre-compact` | Agent is about to compact or compress its context. |
+| `notification` | Agent emitted a notification-style event. |
+| `stop` | Agent finished an interactive turn or stopped naturally. |
+| `session-end` | Agent session ended; summary/handoff path may run. |
+| `other` | Unknown or unsupported hook event. |
+
+Unknown events do **not** expand the enum and, by default, leave no
+source-event metadata in storage; they collapse to `other`. Third-party
+integrations that need their own vocabulary can opt in by sending
+`extension=<namespace>` on `/hook`. With a valid extension namespace,
+ai-memory stores an explicit `source_event=<name>` when provided, or the
+unknown `event` string when `source_event` is omitted. The stored pair is
+nullable observation metadata; `kind` stays canonical. This is an
+extension seam, not a runtime plugin system: external processors must use
+the existing HTTP/MCP APIs and cannot bypass the sanitizer, hook
+backpressure, or single-writer SQLite actor.
+
## Storage architecture
**Two layers, one source of truth.**
diff --git a/evals/src/main.rs b/evals/src/main.rs
index 7f167109..a6e514ba 100644
--- a/evals/src/main.rs
+++ b/evals/src/main.rs
@@ -385,6 +385,8 @@ fn synthesise_observations(fx: &Fixture) -> Vec<Observation> {
.kind
.parse::<ObservationKind>()
.unwrap_or(ObservationKind::Other),
+ extension: None,
+ source_event: None,
title: f.title.clone(),
body: f.body.clone(),
importance: 5,