Skip to content

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 not
rewrite an existing invariant slot unless new observations directly
contradict 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
```