add-graph-object-lookup-and-related-memory-cli-commands

[Smitbafna]

Summary

Implemented graph object lookup and bounded related-memory traversal across the Greplica repository, service, and CLI layers. This adds the ability to retrieve individual graph objects by ID and traverse related graph entities using a configurable breadth-first search (BFS).
Resolve #36

What Changed

Repository Layer (libs/storage/sqlite/repository.ts)

Added repository APIs to support graph lookups and traversal:

• getObjectById(type, id)

  • Performs a direct SQL lookup for graph objects by type (component, flow, claim, edge, or source).
  • Properly deserializes JSON fields for claims and edges before returning results.

• getEdgesForObject(type, id)

  • Retrieves all edges connected to a given object, including both incoming and outgoing relationships.

• getRelatedObjects(repoId, seedType, seedId, maxDepth)

  • Performs a bounded BFS traversal starting from a seed object.
  • Traversal respects repository scope membership and supersession rules.
  • Maximum traversal depth is configurable.
  • Source nodes are included as leaf nodes but are not traversed further.

Service Layer (libs/knowledge-graph/service.ts)

Added service APIs that validate repository state before delegating to the repository layer:

• lookupObject(input, type, id)

  • Validates the target repository.
  • Returns a graph object by type and ID.

• traverseGraph(input, type, id, maxDepth)

  • Validates the repository.

  • Executes bounded BFS traversal.

  • Returns a GraphReadResult containing categorized graph entities:

    • Components
    • Flows
    • Claims
    • Sources
    • Edges

CLI (apps/cli/main.ts)

Added new graph commands:

• greplica graph get <type> <id>

  • Retrieves a graph object by type and ID.
  • Outputs the complete object as JSON.

• greplica graph traverse <type> <id> [--depth <n>]

  • Traverses graph relationships from the specified seed object.
  • Supports configurable traversal depth (default: 1).
  • Outputs categorized traversal results.

Also added validation for:

• Supported graph object types
• Traversal depth values

Usage

greplica graph get claim cm_abc123

greplica graph traverse component comp_a1b2c3 --depth 2

greplica graph get source src_xyz

[Copilot]

Pull request overview

Adds developer-facing graph inspection capabilities (single-object lookup and bounded traversal) to the knowledge-graph stack, exposing them through the CLI for debugging/exploration of the stored SQLite graph.

Changes:

• Added SqliteRepository.getObjectById() and SqliteRepository.getRelatedObjects() to fetch a single graph object and a neighborhood subgraph.
• Added KnowledgeGraphService.lookupObject() and KnowledgeGraphService.traverseGraph() wrappers over the repository.
• Added CLI commands graph get and graph traverse (with --depth) to print JSON/object summaries and traversal results.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
libs/storage/sqlite/repository.ts	Adds object lookup and BFS traversal helpers over the SQLite graph tables/scopes.
libs/knowledge-graph/service.ts	Exposes repository lookup/traversal via service methods.
apps/cli/main.ts	Adds graph get / graph traverse CLI commands and argument parsing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kushalpatil07]

More thought needs to be put into this.
Why are we exposing what we are exposing is very important.

[Smitbafna]

@kushalpatil07 You're right to question what we're exposing. Let me break down the current design vs. what could be improved:

What we're currently exposing:

• graph get <type> <id> → Returns raw object by type
• graph traverse <type> <id> [--depth] → BFS traversal outputting raw categorized results

The issue: We're exposing graph internals (component/flow/claim/edge/source types, BFS depth, edge relationships) directly to the CLI. The user/agent has to understand the graph model to use these.

Suggested improvements with rationale:

1. memory lookup <id> instead of graph get <type> <id>

   • Why: Auto-detects the object type so the caller doesn't need to know whether the ID is a component, flow, or claim. Abstracts away the graph typing.
   • The subjectType() method already exists in the repository for this.

2. memory inspect <id> [--depth <n>] instead of graph traverse <type> <id> [--depth]

   • Why: Combines lookup + 1-hop traversal into a single "show me this object and what's connected to it" command. This is what agents actually need - they want to see an object + its context, not run BFS manually.
   • Default depth=1 gives immediate neighbors, which covers the "quickly see nearby memory" use case.

3. memory related <id> --type <type> instead of raw edge output

   • Why: If agents only need specific related objects (e.g., "what claims are related to this component?"), we filter at the service layer instead of dumping all edges.
   • This reduces cognitive load on the agent.

What are your thoughts on this ? Happy to iterate on the design.