Skip to content

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

Rust

Write sources[].author in the OKF process:<id> actor form

Maxsuel Einsteinb0a23f014427
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ffe69bdc..189ef83e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -164,17 +164,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
(`` [`foo`](foo.md) ``) is still indexed. (#968)
- `export-okf`'s generated `index.md` no longer has a prose sentence outside
its list structure. Some strict OKF v0.2 validators read §11.3 as
- rejecting it. (#960)
+ rejecting it. (#979)
- `export-okf` now backfills a `title` (derived, same as `derive_title`) and
a `description` (from `summary`, else `abstract`) on an exported page when
missing, so a generic OKF consumer sees both §4.1-recommended keys. The
backfill only ever changes the bundle's copy, never the on-disk wiki file.
- (#960)
+ (#979)
- `export-okf` now rewrites a page's local `[[wikilink]]`s to bundle-relative
standard Markdown links, since a generic OKF consumer has no idea what
`[[decisions/b.md]]` means. A cross-project or cross-workspace wikilink has
no Markdown equivalent and ships untouched, as literal `[[...]]` text.
- (#960)
+ (#979)
+- `sources[].author` in conformed frontmatter is now `process:<agent>`
+ (e.g. `process:claude-code`) instead of a bare agent name, matching the
+ OKF actor grammar's `process:<id>` form for automated processes (#979).
+ This changes the default `sources[].author` value written for every page
+ from now on; already-written pages are not retroactively rewritten.
## [2.4.1] - 2026-09-25
diff --git a/crates/ai-memory-core/src/okf.rs b/crates/ai-memory-core/src/okf.rs
index 2d551a55..f014d8fd 100644
--- a/crates/ai-memory-core/src/okf.rs
+++ b/crates/ai-memory-core/src/okf.rs
@@ -127,7 +127,13 @@ pub fn conform_frontmatter(path: &str, frontmatter: &mut Value) {
Value::String(format!("ai-memory://session/{session}")),
);
if let Some(agent) = map.get("agent").and_then(Value::as_str) {
- entry.insert("author".into(), Value::String(agent.to_string()));
+ // The OKF actor grammar (§5.1) requires `<producer>/<version>`
+ // for agents or `process:<id>` for automated processes; a bare
+ // `claude-code` matches neither. We don't track a per-harness
+ // semantic version, so `<producer>/<version>` isn't honestly
+ // derivable — `process:<id>` is the correct, non-fabricated
+ // choice.
+ entry.insert("author".into(), Value::String(format!("process:{agent}")));
}
map.insert("sources".into(), Value::Array(vec![Value::Object(entry)]));
}
@@ -276,7 +282,7 @@ mod tests {
fm["sources"][0]["resource"],
"ai-memory://session/0192aaaa-0000-7000-8000-000000000000"
);
- assert_eq!(fm["sources"][0]["author"], "claude-code");
+ assert_eq!(fm["sources"][0]["author"], "process:claude-code");
assert!(
fm["generated"]["by"]
.as_str()
@@ -373,6 +379,21 @@ mod tests {
assert_eq!(fm["generated"]["by"], "openai-compat/qwen3:32b");
}
+ #[test]
+ fn sources_author_uses_the_process_actor_form() {
+ // OKF §5.1's actor grammar requires `<producer>/<version>` for an
+ // agent or `process:<id>` for an automated process; a bare agent
+ // name like `claude-code` matches neither. We don't track a
+ // per-harness semantic version, so `process:<agent>` is the honest
+ // choice, not a fabricated version.
+ let mut fm = json!({
+ "session_id": "0192aaaa-0000-7000-8000-000000000000",
+ "agent": "codex",
+ });
+ conform_frontmatter("sessions/x.md", &mut fm);
+ assert_eq!(fm["sources"][0]["author"], "process:codex");
+ }
+
#[test]
fn conformance_verdict_requires_a_non_empty_type() {
assert!(!is_conformant(&json!({})));
diff --git a/docs/okf.md b/docs/okf.md
index 25611239..227bac11 100644
--- a/docs/okf.md
+++ b/docs/okf.md
@@ -52,12 +52,12 @@ families. Summary of what conformance requires:
| OKF key | ai-memory source |
|---|---|
| `type` (required) | derived from path family + existing frontmatter: `sessions/` → `Session Summary`, `_rules/` → `Rule`, `gotchas/` → `Gotcha`, `decisions/` → `Decision`, `procedures/` → `Procedure`, `concepts/` → `Concept`, `notes/` → `Note`, `runbooks/` → `Runbook`, `_slots/` → `Invariant`/`State` (from `slot_kind`), `_lint/` → `Lint Report`, `_pending/` → `Pending Note`; `kind:` frontmatter (`fact`/`note`/`procedure`/`decision`) wins over the path default when present |
-| `title` | already written by every producer |
-| `description` | existing `summary` field, when present |
+| `title` | not written by `conform_frontmatter` on the general write path — only an explicit `title:` frontmatter value survives there. `export-okf` backfills a missing/empty `title` at export time from `derive_title` (H1 heading, else path stem); the on-disk wiki file is never touched |
+| `description` | `conform_frontmatter` fills it from `summary` at write time, when present. `export-okf` additionally falls back to `abstract` when `summary` is absent, but only in the exported copy — a page with neither at write time still has no `description` until it is exported |
| `tags` | already written |
| `generated.by` | actor convention: `process:ai-memory/<version>` for the zero-LLM consolidator and system writers; `<provider-model>` (e.g. `openai-compat/qwen3:32b`) for LLM-written pages; `human:<user>` for wiki edits attributed via the watcher |
| `generated.at` | the page version's `updated_at` |
-| `sources` | session provenance: pages already stamped with `session_id`/`agent` get `[{resource: "ai-memory://session/<uuid>", author: "<agent>"}]` |
+| `sources` | session provenance: pages already stamped with `session_id`/`agent` get `[{resource: "ai-memory://session/<uuid>", author: "process:<agent>"}]` — the `process:<id>` actor form (§5.1), since a per-harness semantic version isn't honestly derivable |
| `stale_after` | existing `expires_at` (TTL), when present: an RFC 3339 value verbatim, a bare `YYYY-MM-DD` as the end of that day in UTC (`2026-10-01T23:59:59.999999Z`), since OKF timestamps carry an explicit offset |
| `status` | `deprecated` when TTL-expired but retained; otherwise omitted (spec default `stable`) |