Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(links): cross-project observability — lint, briefing, graph API
Djalma Júnior75f0231457ab
diff --git a/crates/ai-memory-consolidate/src/lint.rs b/crates/ai-memory-consolidate/src/lint.rsindex bc0fc318..13eb509d 100644--- a/crates/ai-memory-consolidate/src/lint.rs+++ b/crates/ai-memory-consolidate/src/lint.rs@@ -107,6 +107,38 @@ pub async fn run_lint(let candidates = reader.decay_candidates(workspace_id, project_id).await?;let mut findings = rule_based_findings(&candidates);+ // Dangling cross-project links: a `[[project:path]]` dependency that does+ // not resolve. A broken inter-project edge is high-signal — surface it+ // even on the zero-LLM path.+ for dangling in reader+ .dangling_cross_project_links(workspace_id, project_id)+ .await?+ {+ let target = match &dangling.workspace {+ Some(ws) => format!("{ws}/{}:{}", dangling.project, dangling.path),+ None => format!("{}:{}", dangling.project, dangling.path),+ };+ let message = if dangling.project_exists {+ format!(+ "Page {} links to {} but that page does not exist in project `{}` \+ (missing, renamed, or deleted) — a broken cross-project dependency",+ dangling.from_path, target, dangling.project,+ )+ } else {+ format!(+ "Page {} links to {} but project `{}` does not exist (typo or wrong name)",+ dangling.from_path, target, dangling.project,+ )+ };+ findings.push(LintFinding {+ kind: "broken_link".into(),+ severity: "warning".into(),+ message,+ pages: vec![dangling.from_path],+ detail: None,+ });+ }+if use_llm && let Some(provider) = llm {match contradiction_pass(provider.clone(),diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex e43cfae7..bf67e24e 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -93,8 +93,8 @@ impl Store {mod tests {use super::*;use ai_memory_core::{- AgentKind, NewObservation, NewPage, NewSession, ObservationId, ObservationKind, PagePath,- ProjectId, SessionId, Tier, WorkspaceId,+ AgentKind, LinkTarget, NewObservation, NewPage, NewSession, ObservationId, ObservationKind,+ PagePath, ProjectId, SessionId, Tier, WorkspaceId,};use rusqlite::{Connection, params};use tempfile::TempDir;@@ -113,6 +113,76 @@ mod tests {}}+ #[tokio::test]+ async fn cross_project_links_surface_in_graph_briefing_and_lint() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let app = store+ .writer+ .get_or_create_project(ws, "app", None)+ .await+ .unwrap();+ let infra = store+ .writer+ .get_or_create_project(ws, "infra", None)+ .await+ .unwrap();++ // Target page in `infra`, then a page in `app` that depends on it+ // plus a dangling link to a non-existent project.+ store+ .writer+ .upsert_page(sample_page(ws, infra, "runbooks/02.md", "the runbook"))+ .await+ .unwrap();+ let mut dep = sample_page(ws, app, "concepts/dep.md", "needs infra + a typo");+ dep.links = vec![+ LinkTarget {+ workspace: None,+ project: Some("infra".into()),+ path: PagePath::new("runbooks/02.md").unwrap(),+ },+ LinkTarget {+ workspace: None,+ project: Some("nope".into()),+ path: PagePath::new("ghost.md").unwrap(),+ },+ ];+ store.writer.upsert_page(dep).await.unwrap();++ // Graph: exactly one resolved cross-project edge, app -> infra.+ let edges = store.reader.cross_project_edges(None).await.unwrap();+ assert_eq!(edges.len(), 1, "one resolved cross-project edge");+ assert_eq!(edges[0].from_project, "app");+ assert_eq!(edges[0].to_project, "infra");++ // Briefing degree: app depends on 1 project; infra has 1 dependent.+ let app_brief = store.reader.briefing_for_project(ws, app, 5).await.unwrap();+ assert_eq!(app_brief.cross_project_dependencies, 1);+ assert_eq!(app_brief.cross_project_dependents, 0);+ let infra_brief = store+ .reader+ .briefing_for_project(ws, infra, 5)+ .await+ .unwrap();+ assert_eq!(infra_brief.cross_project_dependents, 1);++ // Lint: the dangling link to project `nope` is reported as unknown.+ let dangling = store+ .reader+ .dangling_cross_project_links(ws, app)+ .await+ .unwrap();+ assert_eq!(dangling.len(), 1, "only the unresolved `nope` link");+ assert_eq!(dangling[0].project, "nope");+ assert!(!dangling[0].project_exists);+ }+#[tokio::test]async fn open_and_upsert_page() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 64bc6b81..4cd312bf 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -172,6 +172,13 @@ pub struct BriefingSnapshot {pub slots: Vec<BriefingPage>,/// Top-N most-recently-updated `is_latest = 1` pages.pub recent_pages: Vec<BriefingPage>,+ /// Distinct other projects whose pages link INTO this project (who+ /// depends on us). Project-scoped briefings only; `0` for+ /// workspace/global snapshots.+ pub cross_project_dependents: u64,+ /// Distinct other projects this project's pages link OUT to (what we+ /// depend on). Project-scoped briefings only; `0` otherwise.+ pub cross_project_dependencies: u64,}/// Trimmed page view for the briefing — path, title, kind, updated_at@@ -265,6 +272,43 @@ pub struct PageMeta {pub supersedes: Option<String>,}+/// One resolved cross-project edge (a link whose endpoints live in+/// different projects). The `/api/v1/graph` endpoint returns these; the UI+/// builds nodes from the endpoints and can aggregate to a project graph.+#[derive(Debug, Clone, Serialize)]+pub struct CrossProjectEdge {+ /// Source page workspace.+ pub from_workspace: String,+ /// Source page project.+ pub from_project: String,+ /// Source page path.+ pub from_path: String,+ /// Target page workspace.+ pub to_workspace: String,+ /// Target page project.+ pub to_project: String,+ /// Target page path.+ pub to_path: String,+}++/// An unresolved cross-project link — a declared dependency on another+/// project's page that does not resolve. Surfaced by `memory_lint`.+#[derive(Debug, Clone, Serialize)]+pub struct DanglingCrossLink {+ /// Path of the page that authored the link (in the queried project).+ pub from_path: String,+ /// Target workspace name (`None` = the source page's own workspace).+ pub workspace: Option<String>,+ /// Target project name.+ pub project: String,+ /// Target page path within that project.+ pub path: String,+ /// Whether the named target project exists at all. `false` →+ /// likely a typo / wrong name; `true` → the page is missing or was+ /// renamed/deleted in an existing project (a broken dependency).+ pub project_exists: bool,+}+/// A page related to another through the link graph — used by the/// page-view "references / referenced by" panel. Body is omitted; just/// enough to render a clickable row.@@ -1416,6 +1460,8 @@ impl ReaderPool {rules,slots,recent_pages,+ cross_project_dependents: 0,+ cross_project_dependencies: 0,})}).await@@ -1547,6 +1593,8 @@ impl ReaderPool {.into_iter().collect::<Result<Vec<_>, _>>()?;+ let (cross_project_dependents, cross_project_dependencies) =+ cross_project_degree(conn, workspace_id, project_id)?;Ok(BriefingSnapshot {counts,activity_7d,@@ -1556,6 +1604,8 @@ impl ReaderPool {rules,slots,recent_pages,+ cross_project_dependents,+ cross_project_dependencies,})}).await@@ -1747,6 +1797,8 @@ impl ReaderPool {rules,slots,recent_pages,+ cross_project_dependents: 0,+ cross_project_dependencies: 0,})}).await@@ -2165,6 +2217,111 @@ impl ReaderPool {.await}+ /// List unresolved cross-project links authored by pages in this project+ /// — declared dependencies on another project's page that don't resolve.+ /// Each row says whether the named target project exists, so the lint can+ /// tell a typo'd project name from a missing / renamed target page.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn dangling_cross_project_links(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ) -> StoreResult<Vec<DanglingCrossLink>> {+ self.with_conn(move |conn| {+ let mut stmt = conn.prepare(+ "SELECT fp.path, l.to_workspace, l.to_project, l.to_path, \+ EXISTS ( \+ SELECT 1 FROM projects pr \+ JOIN workspaces ws ON ws.id = pr.workspace_id \+ WHERE pr.name = l.to_project \+ AND ws.name = COALESCE( \+ l.to_workspace, \+ (SELECT name FROM workspaces WHERE id = ?1) \+ ) \+ ) AS project_exists \+ FROM links l \+ JOIN pages fp ON fp.id = l.from_page_id \+ AND fp.workspace_id = ?1 AND fp.project_id = ?2 AND fp.is_latest = 1 \+ WHERE l.to_page_id IS NULL AND l.to_project IS NOT NULL \+ ORDER BY fp.path, l.to_project, l.to_path",+ )?;+ let rows = stmt.query_map(+ params![workspace_id.as_bytes(), project_id.as_bytes()],+ |row| {+ let exists: i64 = row.get(4)?;+ Ok(DanglingCrossLink {+ from_path: row.get(0)?,+ workspace: row.get(1)?,+ project: row.get(2)?,+ path: row.get(3)?,+ project_exists: exists != 0,+ })+ },+ )?;+ let mut out = Vec::new();+ for r in rows {+ out.push(r?);+ }+ Ok(out)+ })+ .await+ }++ /// Resolved cross-project edges (links whose endpoints are in different+ /// projects). When `scope` is `Some((ws, proj))`, only edges that touch+ /// that project (as source or target) are returned; `None` returns the+ /// whole cross-project graph. Powers `/api/v1/graph`.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn cross_project_edges(+ &self,+ scope: Option<(WorkspaceId, ProjectId)>,+ ) -> StoreResult<Vec<CrossProjectEdge>> {+ self.with_conn(move |conn| {+ let base = "SELECT fw.name, fpr.name, fp.path, tw.name, tpr.name, tp.path \+ FROM links l \+ JOIN pages fp ON fp.id = l.from_page_id AND fp.is_latest = 1 \+ JOIN pages tp ON tp.id = l.to_page_id AND tp.is_latest = 1 \+ JOIN projects fpr ON fpr.id = fp.project_id \+ JOIN workspaces fw ON fw.id = fp.workspace_id \+ JOIN projects tpr ON tpr.id = tp.project_id \+ JOIN workspaces tw ON tw.id = tp.workspace_id \+ WHERE fp.project_id != tp.project_id";+ let map_row = |row: &rusqlite::Row<'_>| {+ Ok(CrossProjectEdge {+ from_workspace: row.get(0)?,+ from_project: row.get(1)?,+ from_path: row.get(2)?,+ to_workspace: row.get(3)?,+ to_project: row.get(4)?,+ to_path: row.get(5)?,+ })+ };+ let mut out = Vec::new();+ if let Some((_ws, proj)) = scope {+ let sql =+ format!("{base} AND (fp.project_id = ?1 OR tp.project_id = ?1) ORDER BY fw.name, fpr.name, fp.path");+ let mut stmt = conn.prepare(&sql)?;+ let rows = stmt.query_map(params![proj.as_bytes()], map_row)?;+ for r in rows {+ out.push(r?);+ }+ } else {+ let sql = format!("{base} ORDER BY fw.name, fpr.name, fp.path");+ let mut stmt = conn.prepare(&sql)?;+ let rows = stmt.query_map([], map_row)?;+ for r in rows {+ out.push(r?);+ }+ }+ Ok(out)+ })+ .await+ }+/// Return one row per (workspace, project) with page-count and/// last-updated aggregates. Used by the web UI project-list view.///@@ -2974,6 +3131,46 @@ fn count_project(Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))}+/// Cross-project link degree for a project: `(dependents, dependencies)`.+/// `dependents` = distinct other projects whose pages link into this one;+/// `dependencies` = distinct other projects this one links out to. Counts+/// resolved links only (`to_page_id` is set); project ids are globally+/// unique, so a bare `!= project_id` excludes self across all workspaces.+fn cross_project_degree(+ conn: &Connection,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+) -> StoreResult<(u64, u64)> {+ let dependents: Option<i64> = conn+ .query_row(+ "SELECT COUNT(DISTINCT fp.project_id) \+ FROM links l \+ JOIN pages tp ON tp.id = l.to_page_id \+ AND tp.workspace_id = ?1 AND tp.project_id = ?2 AND tp.is_latest = 1 \+ JOIN pages fp ON fp.id = l.from_page_id AND fp.is_latest = 1 \+ WHERE fp.project_id != ?2",+ params![workspace_id.as_bytes(), project_id.as_bytes()],+ |row| row.get(0),+ )+ .optional()?;+ let dependencies: Option<i64> = conn+ .query_row(+ "SELECT COUNT(DISTINCT tp.project_id) \+ FROM links l \+ JOIN pages fp ON fp.id = l.from_page_id \+ AND fp.workspace_id = ?1 AND fp.project_id = ?2 AND fp.is_latest = 1 \+ JOIN pages tp ON tp.id = l.to_page_id AND tp.is_latest = 1 \+ WHERE tp.project_id != ?2",+ params![workspace_id.as_bytes(), project_id.as_bytes()],+ |row| row.get(0),+ )+ .optional()?;+ Ok((+ u64::try_from(dependents.unwrap_or(0)).unwrap_or(0),+ u64::try_from(dependencies.unwrap_or(0)).unwrap_or(0),+ ))+}+fn count_workspace(conn: &Connection, sql: &str, workspace_id: WorkspaceId) -> StoreResult<u64> {let n: Option<i64> = conn.query_row(sql, params![workspace_id.as_bytes()], |row| row.get(0))diff --git a/crates/ai-memory-web/src/routes/api.rs b/crates/ai-memory-web/src/routes/api.rsindex fc0f4624..47eb3da4 100644--- a/crates/ai-memory-web/src/routes/api.rs+++ b/crates/ai-memory-web/src/routes/api.rs@@ -54,6 +54,7 @@ pub(crate) fn build(state: Arc<WebState>) -> Router {"/workspaces/{workspace}/projects/{project}/overview",axum::routing::get(project_overview_handler),)+ .route("/graph", axum::routing::get(graph_handler)).with_state(state)}@@ -91,6 +92,23 @@ async fn workspaces_handler(State(state): State<Arc<WebState>>) -> Result<Respon))}+/// Cross-project dependency graph: every resolved link whose endpoints are+/// in different projects, each carrying both endpoints' workspace/project/+/// path. The UI builds nodes from the endpoints (and may aggregate to a+/// project-level dependency graph). Global for now; project scoping is a+/// follow-up query param.+async fn graph_handler(State(state): State<Arc<WebState>>) -> Result<Response, Response> {+ let edges = state+ .reader+ .cross_project_edges(None)+ .await+ .map_err(internal_error)?;+ Ok(with_cache(+ Json(serde_json::json!({ "edges": edges })).into_response(),+ LIST_CACHE_MAX_AGE,+ ))+}+async fn projects_handler(State(state): State<Arc<WebState>>,Query(query): Query<ProjectListQuery>,diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 6964e359..184a1e95 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -160,7 +160,7 @@ backpressure, or single-writer SQLite actor.| `pages_fts` | FTS5 virtual table over `(title, body)`, auto-synced by triggers. || `sessions`, `observations` | Hook capture, full audit log. || `observations_fts` | FTS5 virtual table over raw observation `(title, body)`, used only as bounded fallback. |-| `links` | Wikilink / markdown cross-references with `to_page_id` nullable for unresolved forward links. |+| `links` | Wikilink / markdown cross-references. `to_page_id` (a global PageId) is nullable for unresolved forward links. `to_workspace` / `to_project` carry a cross-project scope (NULL = the source page's own project). || `handoffs` | Typed cross-agent handoff records (open / accepted / expired). || `page_embeddings` | Optional vector rows for latest pages, with `(provider, model, dim)` denormalised so hybrid search can ignore stale vectors after an embedding config change and report missing-embedding diagnostics. || `audit_log` | Every mutation, addressable by `at DESC`. |@@ -185,6 +185,32 @@ context, identity, rules, or user preferences; consolidation should notrewrite an existing invariant slot unless new observations directlycontradict specific existing content.+## Cross-project links++Pages normally link within their own project (`[[decisions/0001.md]]`,+`[label](../gotchas/x.md)`). A wikilink can also name another project so+that dependencies between projects become explicit edges in the graph:++* `[[project:path.md]]` — a sibling project in the same workspace.+* `[[workspace/project:path.md]]` — a project in another workspace.++The parser (`ai-memory-wiki::extract_links`) yields a `LinkTarget+{ workspace, project, path }`; the store resolves it against the named+project's latest page and records the scope in `links.to_workspace` /+`links.to_project` (NULL = the source's own project, the common case).+Resolution is deferred-safe: a link to a page that does not exist yet+stays `to_page_id = NULL` and is repointed by+`refresh_incoming_links_for_path` when that page later lands — across+projects, not only within one.++Because `to_page_id` is a global id and `ReaderPool::page_links` joins by+id without a project filter, a resolved cross-project link surfaces as a+backlink on its target for free; `RelatedPage` carries the source's+`workspace` / `project` so the dependency is labelled and navigable. This+is what turns the per-project wikis into one dependency graph (see also+the `memory_lint` dangling-ref check, the briefing dependents counts, and+the `/api/v1/graph` endpoint).+## Crate layout```