feat: memories ext

codex-rs/Cargo.toml

@@ -47,6 +47,7 @@ members = [
     "ext/extension-api",
     "ext/guardian",
     "ext/git-attribution",
+    "ext/memories",
     "external-agent-migration",
     "external-agent-sessions",
     "keyring-store",
@@ -179,6 +180,7 @@ codex-linux-sandbox = { path = "linux-sandbox" }
 codex-lmstudio = { path = "lmstudio" }
 codex-login = { path = "login" }
 codex-message-history = { path = "message-history" }
+codex-memories-extension = { path = "ext/memories" }
 codex-memories-read = { path = "memories/read" }
 codex-memories-write = { path = "memories/write" }
 codex-mcp = { path = "codex-mcp" }
@@ -469,6 +471,7 @@ unwrap_used = "deny"
 [workspace.metadata.cargo-shear]
 ignored = [
     "codex-agent-graph-store",
+    "codex-memories-extension",
     "icu_provider",
     "openssl-sys",
     "codex-v8-poc",

codex-rs/ext/memories/BUILD.bazel

@@ -0,0 +1,6 @@
+load("//:defs.bzl", "codex_rust_crate")
+
+codex_rust_crate(
+    name = "memories",
+    crate_name = "codex_memories_extension",
+)

codex-rs/ext/memories/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+edition.workspace = true
+license.workspace = true
+name = "codex-memories-extension"
+version.workspace = true
+
+[lib]
+name = "codex_memories_extension"
+path = "src/lib.rs"
+doctest = false
+
+[lints]
+workspace = true
+
+[dependencies]
+codex-core = { workspace = true }
+codex-extension-api = { workspace = true }
+codex-features = { workspace = true }
+codex-memories-read = { workspace = true }
+codex-utils-absolute-path = { workspace = true }
+codex-utils-output-truncation = { workspace = true }
+schemars = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["fs"] }
+
+[dev-dependencies]
+codex-tools = { workspace = true }
+pretty_assertions = { workspace = true }
+tempfile = { workspace = true }
+tokio = { workspace = true, features = ["fs", "macros"] }

codex-rs/ext/memories/src/backend.rs

@@ -0,0 +1,164 @@
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use std::future::Future;
+
+pub const DEFAULT_LIST_MAX_RESULTS: usize = 2_000;
+pub const MAX_LIST_RESULTS: usize = 2_000;
+pub const DEFAULT_SEARCH_MAX_RESULTS: usize = 200;
+pub const MAX_SEARCH_RESULTS: usize = 200;
+pub const DEFAULT_READ_MAX_TOKENS: usize = 20_000;
+
+/// Storage interface behind the memories MCP tools.
+///
+/// Implementations should return paths relative to the memory store and enforce
+/// their own storage-specific access rules. The local implementation uses the
+/// filesystem today; a later implementation can satisfy the same contract from a
+/// remote backend.
+pub trait MemoriesBackend: Clone + Send + Sync + 'static {
+    fn list(
+        &self,
+        request: ListMemoriesRequest,
+    ) -> impl Future<Output = Result<ListMemoriesResponse, MemoriesBackendError>> + Send;
+
+    fn read(
+        &self,
+        request: ReadMemoryRequest,
+    ) -> impl Future<Output = Result<ReadMemoryResponse, MemoriesBackendError>> + Send;
+
+    fn search(
+        &self,
+        request: SearchMemoriesRequest,
+    ) -> impl Future<Output = Result<SearchMemoriesResponse, MemoriesBackendError>> + Send;
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ListMemoriesRequest {
+    pub path: Option<String>,
+    pub cursor: Option<String>,
+    pub max_results: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ListMemoriesResponse {
+    pub path: Option<String>,
+    pub entries: Vec<MemoryEntry>,
+    pub next_cursor: Option<String>,
+    pub truncated: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReadMemoryRequest {
+    pub path: String,
+    pub line_offset: usize,
+    pub max_lines: Option<usize>,
+    pub max_tokens: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ReadMemoryResponse {
+    pub path: String,
+    pub start_line_number: usize,
+    pub content: String,
+    pub truncated: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SearchMemoriesRequest {
+    pub queries: Vec<String>,
+    pub match_mode: SearchMatchMode,
+    pub path: Option<String>,
+    pub cursor: Option<String>,
+    pub context_lines: usize,
+    pub case_sensitive: bool,
+    pub normalized: bool,
+    pub max_results: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct SearchMemoriesResponse {
+    pub queries: Vec<String>,
+    pub match_mode: SearchMatchMode,
+    pub path: Option<String>,
+    pub matches: Vec<MemorySearchMatch>,
+    pub next_cursor: Option<String>,
+    pub truncated: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum SearchMatchMode {
+    Any,
+    AllOnSameLine,
+    AllWithinLines {
+        #[schemars(range(min = 1))]
+        line_count: usize,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct MemoryEntry {
+    pub path: String,
+    pub entry_type: MemoryEntryType,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum MemoryEntryType {
+    File,
+    Directory,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct MemorySearchMatch {
+    pub path: String,
+    pub match_line_number: usize,
+    pub content_start_line_number: usize,
+    pub content: String,
+    pub matched_queries: Vec<String>,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum MemoriesBackendError {
+    #[error("path '{path}' {reason}")]
+    InvalidPath { path: String, reason: String },
+    #[error("cursor '{cursor}' {reason}")]
+    InvalidCursor { cursor: String, reason: String },
+    #[error("path '{path}' was not found")]
+    NotFound { path: String },
+    #[error("line_offset must be a 1-indexed line number")]
+    InvalidLineOffset,
+    #[error("max_lines must be a positive integer")]
+    InvalidMaxLines,
+    #[error("line_offset exceeds file length")]
+    LineOffsetExceedsFileLength,
+    #[error("path '{path}' is not a file")]
+    NotFile { path: String },
+    #[error("queries must not be empty or contain empty strings")]
+    EmptyQuery,
+    #[error("all_within_lines.line_count must be a positive integer")]
+    InvalidMatchWindow,
+    #[error("I/O error while reading memories: {0}")]
+    Io(#[from] std::io::Error),
+}
+
+impl MemoriesBackendError {
+    pub fn invalid_path(path: impl Into<String>, reason: impl Into<String>) -> Self {
+        Self::InvalidPath {
+            path: path.into(),
+            reason: reason.into(),
+        }
+    }
+
+    pub fn invalid_cursor(cursor: impl Into<String>, reason: impl Into<String>) -> Self {
+        Self::InvalidCursor {
+            cursor: cursor.into(),
+            reason: reason.into(),
+        }
+    }
+}