Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat: add context service with entity extraction, seeding, expansion, and ranking
riley02279bb79bced65f
diff --git a/memory-layer/src/main/scala/ix/memory/context/ClaimCollector.scala b/memory-layer/src/main/scala/ix/memory/context/ClaimCollector.scalanew file mode 100644index 00000000..9b5e440e--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/ClaimCollector.scala@@ -0,0 +1,15 @@+package ix.memory.context++import cats.effect.IO+import cats.syntax.traverse._++import ix.memory.db.GraphQueryApi+import ix.memory.model._++class ClaimCollector(queryApi: GraphQueryApi) {++ def collect(tenant: TenantId, nodeIds: Vector[NodeId]): IO[Vector[Claim]] =+ nodeIds+ .traverse(id => queryApi.getClaims(tenant, id))+ .map(_.flatten.distinctBy(_.id))+}diff --git a/memory-layer/src/main/scala/ix/memory/context/ConfidenceScorer.scala b/memory-layer/src/main/scala/ix/memory/context/ConfidenceScorer.scalanew file mode 100644index 00000000..e645ef96--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/ConfidenceScorer.scala@@ -0,0 +1,23 @@+package ix.memory.context++import ix.memory.model._++trait ConfidenceScorer {+ def score(claim: Claim, latestRev: Rev): ScoredClaim+}++/** Stub implementation for Phase 1 -- Task 8 will replace this. */+class DefaultConfidenceScorer extends ConfidenceScorer {++ def score(claim: Claim, latestRev: Rev): ScoredClaim = {+ val baseAuth = SourceType.baseAuthority(claim.provenance.sourceType)+ val breakdown = ConfidenceBreakdown(+ baseAuthority = Factor(baseAuth, s"${claim.provenance.sourceType}"),+ verification = Factor(1.0, "no verification data"),+ recency = Factor(1.0, "default recency"),+ corroboration = Factor(1.0, "default corroboration"),+ conflictPenalty = Factor(1.0, "no conflicts detected")+ )+ ScoredClaim(claim, breakdown)+ }+}diff --git a/memory-layer/src/main/scala/ix/memory/context/ConflictDetector.scala b/memory-layer/src/main/scala/ix/memory/context/ConflictDetector.scalanew file mode 100644index 00000000..faba71b4--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/ConflictDetector.scala@@ -0,0 +1,14 @@+package ix.memory.context++import ix.memory.model._++trait ConflictDetector {+ def detect(claims: Vector[ScoredClaim]): Vector[ConflictReport]+}++/** Stub implementation for Phase 1 -- Task 9 will replace this. */+class DefaultConflictDetector extends ConflictDetector {++ def detect(claims: Vector[ScoredClaim]): Vector[ConflictReport] =+ Vector.empty // No conflict detection yet+}diff --git a/memory-layer/src/main/scala/ix/memory/context/ContextRanker.scala b/memory-layer/src/main/scala/ix/memory/context/ContextRanker.scalanew file mode 100644index 00000000..1d639146--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/ContextRanker.scala@@ -0,0 +1,9 @@+package ix.memory.context++import ix.memory.model.ScoredClaim++object ContextRanker {++ def rank(claims: Vector[ScoredClaim]): Vector[ScoredClaim] =+ claims.sortBy(-_.confidence.score)+}diff --git a/memory-layer/src/main/scala/ix/memory/context/ContextService.scala b/memory-layer/src/main/scala/ix/memory/context/ContextService.scalanew file mode 100644index 00000000..05273886--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/ContextService.scala@@ -0,0 +1,56 @@+package ix.memory.context++import cats.effect.IO++import ix.memory.db.GraphQueryApi+import ix.memory.model._++class ContextService(+ queryApi: GraphQueryApi,+ seeder: GraphSeeder,+ expander: GraphExpander,+ claimCollector: ClaimCollector,+ confidenceScorer: ConfidenceScorer,+ conflictDetector: ConflictDetector+) {++ def query(tenant: TenantId, question: String,+ asOfRev: Option[Rev] = None): IO[StructuredContext] =+ for {+ // 1. Extract entity keywords from the natural language query+ terms <- IO.pure(EntityExtractor.extract(question))++ // 2. Seed: search the graph for nodes matching extracted terms+ seeds <- seeder.seed(tenant, terms, asOfRev)++ // 3. Expand: traverse the graph 1 hop from each seed+ expanded <- expander.expand(tenant, seeds.map(_.id), hops = 1, asOfRev = asOfRev)++ // 4. Collect claims for all discovered nodes+ allNodeIds = (seeds.map(_.id) ++ expanded.nodes.map(_.id)).distinct+ claims <- claimCollector.collect(tenant, allNodeIds)++ // 5. Score each claim+ rev <- asOfRev.fold(queryApi.getLatestRev(tenant))(IO.pure)+ scored = claims.map(c => confidenceScorer.score(c, rev))++ // 6. Detect conflicts among scored claims+ conflicts = conflictDetector.detect(scored)++ // 7. Rank claims by confidence (descending)+ ranked = ContextRanker.rank(scored)++ // 8. Assemble and return StructuredContext+ } yield StructuredContext(+ claims = ranked.toList,+ conflicts = conflicts.toList,+ nodes = (seeds ++ expanded.nodes).distinctBy(_.id).toList,+ edges = expanded.edges.toList,+ metadata = ContextMetadata(+ query = question,+ seedEntities = seeds.map(_.id).toList,+ hopsExpanded = 1,+ asOfRev = rev+ )+ )+}diff --git a/memory-layer/src/main/scala/ix/memory/context/EntityExtractor.scala b/memory-layer/src/main/scala/ix/memory/context/EntityExtractor.scalanew file mode 100644index 00000000..dca489be--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/EntityExtractor.scala@@ -0,0 +1,18 @@+package ix.memory.context++object EntityExtractor {++ private val stopwords = Set(+ "how", "does", "the", "is", "a", "an", "what", "when", "where", "why",+ "do", "it", "in", "of", "to", "for", "and", "or", "not", "with", "by",+ "from", "at", "on", "this", "that", "are", "was", "be", "has", "have", "can"+ )++ def extract(query: String): Vector[String] =+ query.toLowerCase+ .split("[\\s,;.!?]+")+ .map(_.trim)+ .filter(w => w.nonEmpty && w.length > 1 && !stopwords.contains(w))+ .toVector+ .distinct+}diff --git a/memory-layer/src/main/scala/ix/memory/context/GraphExpander.scala b/memory-layer/src/main/scala/ix/memory/context/GraphExpander.scalanew file mode 100644index 00000000..d4e70046--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/GraphExpander.scala@@ -0,0 +1,23 @@+package ix.memory.context++import cats.effect.IO+import cats.syntax.traverse._++import ix.memory.db.{GraphQueryApi, Direction, ExpandResult}+import ix.memory.model._++class GraphExpander(queryApi: GraphQueryApi) {++ def expand(tenant: TenantId, seeds: Vector[NodeId], hops: Int = 1,+ predicates: Option[Set[String]] = None,+ asOfRev: Option[Rev] = None): IO[ExpandResult] =+ seeds+ .traverse { nodeId =>+ queryApi.expand(tenant, nodeId, Direction.Both, predicates, hops, asOfRev)+ }+ .map { results =>+ val allNodes = results.flatMap(_.nodes).distinctBy(_.id)+ val allEdges = results.flatMap(_.edges).distinctBy(_.id)+ ExpandResult(allNodes, allEdges)+ }+}diff --git a/memory-layer/src/main/scala/ix/memory/context/GraphSeeder.scala b/memory-layer/src/main/scala/ix/memory/context/GraphSeeder.scalanew file mode 100644index 00000000..9ab51aa3--- /dev/null+++ b/memory-layer/src/main/scala/ix/memory/context/GraphSeeder.scala@@ -0,0 +1,16 @@+package ix.memory.context++import cats.effect.IO+import cats.syntax.traverse._++import ix.memory.db.GraphQueryApi+import ix.memory.model._++class GraphSeeder(queryApi: GraphQueryApi) {++ def seed(tenant: TenantId, terms: Vector[String],+ asOfRev: Option[Rev] = None): IO[Vector[GraphNode]] =+ terms+ .traverse(term => queryApi.searchNodes(tenant, term))+ .map(_.flatten.distinctBy(_.id))+}diff --git a/memory-layer/src/test/scala/ix/memory/context/ContextServiceSpec.scala b/memory-layer/src/test/scala/ix/memory/context/ContextServiceSpec.scalanew file mode 100644index 00000000..0677a958--- /dev/null+++ b/memory-layer/src/test/scala/ix/memory/context/ContextServiceSpec.scala@@ -0,0 +1,241 @@+package ix.memory.context++import java.time.Instant+import java.util.UUID++import cats.effect.IO+import cats.effect.testing.scalatest.AsyncIOSpec+import io.circe.Json+import org.scalatest.flatspec.AsyncFlatSpec+import org.scalatest.matchers.should.Matchers++import ix.memory.db._+import ix.memory.model._++class ContextServiceSpec extends AsyncFlatSpec with AsyncIOSpec with Matchers {++ val clientResource = ArangoClient.resource(+ host = "localhost", port = 8529,+ database = "ix_memory_test", user = "root", password = ""+ )++ private def makePatch(+ tenant: TenantId,+ baseRev: Rev = Rev(0L),+ ops: Vector[PatchOp] = Vector.empty,+ patchId: PatchId = PatchId(UUID.randomUUID())+ ): GraphPatch =+ GraphPatch(+ patchId = patchId,+ tenant = tenant,+ actor = "test-actor",+ timestamp = Instant.parse("2025-06-01T12:00:00Z"),+ source = PatchSource(+ uri = "test://source",+ sourceHash = Some("hash123"),+ extractor = "test-extractor",+ sourceType = SourceType.Code+ ),+ baseRev = baseRev,+ ops = ops,+ replaces = Vector.empty,+ intent = Some("test intent")+ )++ private def buildContextService(queryApi: GraphQueryApi): ContextService = {+ val seeder = new GraphSeeder(queryApi)+ val expander = new GraphExpander(queryApi)+ val collector = new ClaimCollector(queryApi)+ val scorer = new DefaultConfidenceScorer()+ val detector = new DefaultConflictDetector()+ new ContextService(queryApi, seeder, expander, collector, scorer, detector)+ }++ // ── Test 1: Full pipeline returns structured context ───────────────++ "ContextService" should "return structured context for a query" in {+ clientResource.use { client =>+ val writeApi = new ArangoGraphWriteApi(client)+ val queryApi = new ArangoGraphQueryApi(client)+ val tenant = TenantId(UUID.randomUUID())++ val billingId = NodeId(UUID.nameUUIDFromBytes(s"${tenant.value}:test:billing_service".getBytes))+ val retryId = NodeId(UUID.nameUUIDFromBytes(s"${tenant.value}:test:retry_handler".getBytes))+ val edgeId = EdgeId(UUID.randomUUID())++ val contextService = buildContextService(queryApi)++ val patch = makePatch(+ tenant = tenant,+ ops = Vector(+ PatchOp.UpsertNode(billingId, NodeKind.Function, "billing_service", Map.empty[String, Json]),+ PatchOp.UpsertNode(retryId, NodeKind.Function, "retry_handler", Map.empty[String, Json]),+ PatchOp.UpsertEdge(edgeId, billingId, retryId, EdgePredicate("calls"), Map.empty[String, Json]),+ PatchOp.AssertClaim(billingId, "handles_billing", Json.fromString("true"), Some(0.9))+ )+ )++ for {+ _ <- client.ensureSchema()+ _ <- writeApi.commitPatch(patch)+ result <- contextService.query(tenant, "How does billing retry?")+ } yield {+ result.nodes should not be empty+ result.metadata.query shouldBe "How does billing retry?"+ // seedEntities is List[NodeId] — verify at least 1 seed was found+ result.metadata.seedEntities should not be empty+ result.metadata.hopsExpanded shouldBe 1+ }+ }+ }++ // ── Test 2: Empty context for unknown query ────────────────────────++ it should "return empty context for unknown query" in {+ clientResource.use { client =>+ val queryApi = new ArangoGraphQueryApi(client)+ val tenant = TenantId(UUID.randomUUID())+ val contextService = buildContextService(queryApi)++ for {+ _ <- client.ensureSchema()+ result <- contextService.query(tenant, "something totally unknown xyz123")+ } yield {+ result.nodes shouldBe empty+ result.claims shouldBe empty+ }+ }+ }++ // ── Test 3: EntityExtractor extracts meaningful terms ──────────────++ it should "extract meaningful terms from queries" in {+ val terms = EntityExtractor.extract("How does billing retry?")+ terms should contain("billing")+ terms should contain("retry")+ terms should not contain ("how")+ terms should not contain ("does")+ }++ // ── Test 4: Claims are scored and ranked ───────────────────────────++ it should "score and rank claims by confidence" in {+ clientResource.use { client =>+ val writeApi = new ArangoGraphWriteApi(client)+ val queryApi = new ArangoGraphQueryApi(client)+ val tenant = TenantId(UUID.randomUUID())++ val nodeId = NodeId(UUID.randomUUID())++ val contextService = buildContextService(queryApi)++ val patch = makePatch(+ tenant = tenant,+ ops = Vector(+ PatchOp.UpsertNode(nodeId, NodeKind.Function, "billing_func", Map.empty[String, Json]),+ PatchOp.AssertClaim(nodeId, "returns_int", Json.fromString("true"), Some(0.9)),+ PatchOp.AssertClaim(nodeId, "billing_logic", Json.fromString("complex"), Some(0.8))+ )+ )++ for {+ _ <- client.ensureSchema()+ _ <- writeApi.commitPatch(patch)+ result <- contextService.query(tenant, "What does billing do?")+ } yield {+ result.claims should not be empty+ // All claims should have a score > 0+ result.claims.foreach { sc =>+ sc.confidence.score should be > 0.0+ }+ // Claims should be sorted descending by score+ val scores = result.claims.map(_.confidence.score)+ scores shouldBe scores.sorted.reverse+ }+ }+ }++ // ── Test 5: GraphExpander returns connected nodes ──────────────────++ it should "expand seeds to find connected nodes" in {+ clientResource.use { client =>+ val writeApi = new ArangoGraphWriteApi(client)+ val queryApi = new ArangoGraphQueryApi(client)+ val tenant = TenantId(UUID.randomUUID())++ val billingId = NodeId(UUID.randomUUID())+ val retryId = NodeId(UUID.randomUUID())+ val edgeId = EdgeId(UUID.randomUUID())++ val contextService = buildContextService(queryApi)++ val patch = makePatch(+ tenant = tenant,+ ops = Vector(+ PatchOp.UpsertNode(billingId, NodeKind.Service, "billing_service", Map.empty[String, Json]),+ PatchOp.UpsertNode(retryId, NodeKind.Function, "retry_logic", Map.empty[String, Json]),+ PatchOp.UpsertEdge(edgeId, billingId, retryId, EdgePredicate("calls"), Map.empty[String, Json])+ )+ )++ for {+ _ <- client.ensureSchema()+ _ <- writeApi.commitPatch(patch)+ result <- contextService.query(tenant, "How does billing work?")+ } yield {+ // Should find billing_service as seed, then expand to find retry_logic+ result.nodes.length should be >= 1+ result.edges should not be empty+ }+ }+ }++ // ── Test 6: DefaultConflictDetector returns empty ──────────────────++ it should "return empty conflicts with default detector" in {+ clientResource.use { client =>+ val writeApi = new ArangoGraphWriteApi(client)+ val queryApi = new ArangoGraphQueryApi(client)+ val tenant = TenantId(UUID.randomUUID())++ val nodeId = NodeId(UUID.randomUUID())+ val contextService = buildContextService(queryApi)++ val patch = makePatch(+ tenant = tenant,+ ops = Vector(+ PatchOp.UpsertNode(nodeId, NodeKind.Function, "billing_calc", Map.empty[String, Json]),+ PatchOp.AssertClaim(nodeId, "billing_info", Json.fromString("test"), Some(0.9))+ )+ )++ for {+ _ <- client.ensureSchema()+ _ <- writeApi.commitPatch(patch)+ result <- contextService.query(tenant, "billing info")+ } yield {+ result.conflicts shouldBe empty+ }+ }+ }++ // ── Test 7: ContextRanker sorts correctly ──────────────────────────++ it should "rank claims in descending confidence order" in {+ val prov = Provenance("test://uri", None, "test", SourceType.Code, Instant.now())+ val claim1 = Claim(ClaimId(UUID.randomUUID()), NodeId(UUID.randomUUID()), "field1",+ ClaimStatus.Active, prov, Rev(1L), None)+ val claim2 = Claim(ClaimId(UUID.randomUUID()), NodeId(UUID.randomUUID()), "field2",+ ClaimStatus.Active, prov, Rev(1L), None)++ val scored1 = ScoredClaim(claim1, ConfidenceBreakdown(+ Factor(0.5, "low"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok")+ ))+ val scored2 = ScoredClaim(claim2, ConfidenceBreakdown(+ Factor(0.9, "high"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok")+ ))++ val ranked = ContextRanker.rank(Vector(scored1, scored2))+ ranked.head.confidence.score should be > ranked.last.confidence.score+ }+}