| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 4 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 1 | 2 | 0% |
What each file covers
Sections
0 shared · 6 only in A · 4 only in B- − Subgraphs and Workflow Orchestration
- − LangGraph Core Concept
- − Key Components
- − Designing Subgraphs
- − Example Flows
- − Persistence with Subgraphs
- + Memory Management Guidelines
- + Purpose of Memory
- + Implementation Details (`src/memory/`)
- + Best Practices for Memory
Commands
neither file has anySection tags
0 shared · 1 only in A · 2 only in B- − agent-behaviour
- + code-style
- + performance
Line diff
ssdeanx/langgraph-dm · .clinerules/subgraphs.md
@@ −1 @@
1---
2glob: "**/*.ts"
3description: "Langgraph Subgraphs & Workflow Orchestration"
4---
5# Subgraphs and Workflow Orchestration
6
7## LangGraph Core Concept
8
9* This project heavily utilizes LangGraph's `StateGraph` to define and manage complex, multi-step AI agent workflows.
10* A "graph" represents the flow of control and data between different nodes (which are typically agents or tool calls).
11* Subgraphs allow you to reuse an existing graph as a node within another graph, promoting modularity and hierarchical organization.
12
13## Key Components
14
15* **Nodes:** Represent individual steps or agents in the workflow (e.g., `entryNode`, `supervisor`, `reactAgent`, `research_collectNode`). Each node takes the current `AgentState` as input and returns an updated state.
16* **Edges:** Define the transitions between nodes.
17 * **Normal Edges:** Unconditionally move from one node to another (e.g., `START` to `entry`, `chat` to `END`).
18 * **Conditional Edges:** Route to different nodes based on a decision function (e.g., `routeMessages` from `supervisor` to various agents). The routing function takes the `AgentState` and returns the name of the next node(s) or `END`.
19* **`AgentState`:** The central data structure that is passed and modified across all nodes in the graph, maintaining the conversation context and agent-specific data. Defined using `Annotation`.
20* **Supervisor:** A critical node responsible for intelligently routing the `AgentState` to the appropriate specialized agent or action based on the current context and goal.
21* **`Command` Primitive:** Allows combining state updates and control flow (routing) within a single node, useful for dynamic handoffs between agents.
22
23## Designing Subgraphs
24
25* **Modularity:** Complex workflows should be broken down into smaller, manageable subgraphs or sequences of nodes.
26* **Clear Responsibilities:** Each node and subgraph should have a clear, single responsibility.
27* **State Flow:** Pay close attention to how data flows through the `AgentState` between nodes to ensure necessary information is available at each step.
28* **Error Handling:** Design subgraphs to handle errors gracefully, potentially returning control to a supervisor for re-routing or error reporting.
29* **Routing Logic:** The `routeMessages` function (or similar conditional routing) is crucial for dynamic and intelligent workflow execution. Ensure its logic covers all necessary transitions and fallback scenarios.
30* **Communication:**
31 * If the parent graph and subgraph share schema keys (channels), the compiled subgraph can be added directly as a node.
32 * If schemas are different, define a node function that explicitly invokes the subgraph, transforming input state and output results to match the parent's schema. This prevents errors due to non-overlapping channels.
33* **Nesting:** Subgraphs can be nested to any level, allowing for highly complex hierarchical agent systems.
34
35## Example Flows
36
37* **General Conversation:** `entry` -> `supervisor` -> `chat` -> `END`
38* **Research Task:** `entry` -> `supervisor` -> `research_collect` -> `research_summarize` -> `research_report` -> `supervisor` (for final response)
39* **Documentation Task:** `entry` -> `supervisor` -> `draft_documentation` -> `finalize_documentation` -> `supervisor` (for final response)
40* **React Agent Task:** `entry` -> `supervisor` -> `react` -> `supervisor` (for tool execution or further action)
41* **Multi-agent Network:** Agents can communicate with each other in a many-to-many fashion, making decisions on which agent to call next (e.g., `travel_advisor` -> `sightseeing_advisor` -> `hotel_advisor`).
42
43## Persistence with Subgraphs
44
45* Checkpointers should be passed only when compiling the *parent* graph. LangGraph automatically propagates the checkpointer to child subgraphs, enabling persistence across nested levels.
46* State of subgraphs can be viewed and updated, facilitating human-in-the-loop interactions and debugging within nested workflows.
47
ssdeanx/langgraph-dm · .clinerules/memory.md
@@ +1 @@
1---
2glob: "**/*.ts"
3description: "Langgraph Memory Management Guidelines"
4---
5# Memory Management Guidelines
6
7## Purpose of Memory
8
9Memory in AI applications allows agents to process, store, and effectively recall information from past interactions, enabling learning and adaptation to user preferences.
10
11* **Short-term Memory (Thread-scoped):** Persists conversational turns (`messages`) within a single session for context and continuity. Managed as part of the agent's state.
12* **Long-term Memory (Cross-thread):** Retains information across different conversations or users. Stored in custom namespaces via the `Store` interface.
13* **Checkpointing:** Saves snapshots of the graph state at every "super-step" for continuity, debugging, and fault tolerance.
14
15## Implementation Details (`src/memory/`)
16
17* **MongoDB Integration:** MongoDB is the primary backend for memory persistence, including chat history, vector stores, and checkpoints.
18* **`MongoDBSaver` (`@langchain/langgraph-checkpoint-mongodb`):** Used for LangGraph checkpointing, ensuring graph state can be saved and reloaded.
19* **`MongoDBStore`:** Provides a generic key-value store interface over MongoDB for various data types, supporting long-term memory.
20* **`MongoDBChatMessageHistory`:** Manages the storage and retrieval of chat messages in MongoDB.
21* **`MongoDBAtlasVectorSearch`:** Integrates with MongoDB Atlas Vector Search for efficient semantic search over embeddings. Uses Google embeddings.
22
23## Best Practices for Memory
24
25* **Session Management:** Ensure unique `sessionId`s are used for different conversations to maintain isolated contexts.
26* **Environment Variables:** `MONGODB_ATLAS_URI` must be set for database connection.
27* **Vector Indexing:** Ensure vector search indexes are properly created and maintained for efficient vector lookups (e.g., `vector_index` in `src/memory/storage.ts`). Note that Google embeddings are typically 768 dimensions.
28* **Data Consistency:** Be mindful of data consistency when updating and retrieving memory components.
29* **Scalability:** Consider the implications of memory storage on scalability for large-scale deployments.
30* **Managing Conversation History:** Implement strategies to manage long conversation histories (e.g., trimming, summarizing) to prevent context window overflow and reduce costs. The `MessagesAnnotation` with `messagesStateReducer` is crucial for handling message updates and deletions.
31* **Memory Store Usage:** Use the `Store` interface for cross-thread persistence. Define clear namespaces and keys for organizing memories. Implement semantic search for natural language retrieval.
32* **Writing Memories:** Decide whether to write memories "on the hot path" (real-time, potentially impacting latency) or "in the background" (as a separate task).
33* **Memory Representation:** Consider how memories are presented to the LLM (e.g., as updated instructions, few-shot examples) to optimize its performance.
34
@@ −1 +1 @@
11 ---
22 glob: "**/*.ts"
3−description: "Langgraph Subgraphs & Workflow Orchestration"
3+description: "Langgraph Memory Management Guidelines"
44 ---
5−# Subgraphs and Workflow Orchestration
5+# Memory Management Guidelines
66
7−## LangGraph Core Concept
7+## Purpose of Memory
88
9−* This project heavily utilizes LangGraph's `StateGraph` to define and manage complex, multi-step AI agent workflows.
10−* A "graph" represents the flow of control and data between different nodes (which are typically agents or tool calls).
11−* Subgraphs allow you to reuse an existing graph as a node within another graph, promoting modularity and hierarchical organization.
9+Memory in AI applications allows agents to process, store, and effectively recall information from past interactions, enabling learning and adaptation to user preferences.
1210
13−## Key Components
11+* **Short-term Memory (Thread-scoped):** Persists conversational turns (`messages`) within a single session for context and continuity. Managed as part of the agent's state.
12+* **Long-term Memory (Cross-thread):** Retains information across different conversations or users. Stored in custom namespaces via the `Store` interface.
13+* **Checkpointing:** Saves snapshots of the graph state at every "super-step" for continuity, debugging, and fault tolerance.
1414
15−* **Nodes:** Represent individual steps or agents in the workflow (e.g., `entryNode`, `supervisor`, `reactAgent`, `research_collectNode`). Each node takes the current `AgentState` as input and returns an updated state.
16−* **Edges:** Define the transitions between nodes.
17− * **Normal Edges:** Unconditionally move from one node to another (e.g., `START` to `entry`, `chat` to `END`).
18− * **Conditional Edges:** Route to different nodes based on a decision function (e.g., `routeMessages` from `supervisor` to various agents). The routing function takes the `AgentState` and returns the name of the next node(s) or `END`.
19−* **`AgentState`:** The central data structure that is passed and modified across all nodes in the graph, maintaining the conversation context and agent-specific data. Defined using `Annotation`.
20−* **Supervisor:** A critical node responsible for intelligently routing the `AgentState` to the appropriate specialized agent or action based on the current context and goal.
21−* **`Command` Primitive:** Allows combining state updates and control flow (routing) within a single node, useful for dynamic handoffs between agents.
15+## Implementation Details (`src/memory/`)
2216
23−## Designing Subgraphs
17+* **MongoDB Integration:** MongoDB is the primary backend for memory persistence, including chat history, vector stores, and checkpoints.
18+* **`MongoDBSaver` (`@langchain/langgraph-checkpoint-mongodb`):** Used for LangGraph checkpointing, ensuring graph state can be saved and reloaded.
19+* **`MongoDBStore`:** Provides a generic key-value store interface over MongoDB for various data types, supporting long-term memory.
20+* **`MongoDBChatMessageHistory`:** Manages the storage and retrieval of chat messages in MongoDB.
21+* **`MongoDBAtlasVectorSearch`:** Integrates with MongoDB Atlas Vector Search for efficient semantic search over embeddings. Uses Google embeddings.
2422
25−* **Modularity:** Complex workflows should be broken down into smaller, manageable subgraphs or sequences of nodes.
26−* **Clear Responsibilities:** Each node and subgraph should have a clear, single responsibility.
27−* **State Flow:** Pay close attention to how data flows through the `AgentState` between nodes to ensure necessary information is available at each step.
28−* **Error Handling:** Design subgraphs to handle errors gracefully, potentially returning control to a supervisor for re-routing or error reporting.
29−* **Routing Logic:** The `routeMessages` function (or similar conditional routing) is crucial for dynamic and intelligent workflow execution. Ensure its logic covers all necessary transitions and fallback scenarios.
30−* **Communication:**
31− * If the parent graph and subgraph share schema keys (channels), the compiled subgraph can be added directly as a node.
32− * If schemas are different, define a node function that explicitly invokes the subgraph, transforming input state and output results to match the parent's schema. This prevents errors due to non-overlapping channels.
33−* **Nesting:** Subgraphs can be nested to any level, allowing for highly complex hierarchical agent systems.
23+## Best Practices for Memory
3424
35−## Example Flows
36−
37−* **General Conversation:** `entry` -> `supervisor` -> `chat` -> `END`
38−* **Research Task:** `entry` -> `supervisor` -> `research_collect` -> `research_summarize` -> `research_report` -> `supervisor` (for final response)
39−* **Documentation Task:** `entry` -> `supervisor` -> `draft_documentation` -> `finalize_documentation` -> `supervisor` (for final response)
40−* **React Agent Task:** `entry` -> `supervisor` -> `react` -> `supervisor` (for tool execution or further action)
41−* **Multi-agent Network:** Agents can communicate with each other in a many-to-many fashion, making decisions on which agent to call next (e.g., `travel_advisor` -> `sightseeing_advisor` -> `hotel_advisor`).
42−
43−## Persistence with Subgraphs
44−
45−* Checkpointers should be passed only when compiling the *parent* graph. LangGraph automatically propagates the checkpointer to child subgraphs, enabling persistence across nested levels.
46−* State of subgraphs can be viewed and updated, facilitating human-in-the-loop interactions and debugging within nested workflows.
25+* **Session Management:** Ensure unique `sessionId`s are used for different conversations to maintain isolated contexts.
26+* **Environment Variables:** `MONGODB_ATLAS_URI` must be set for database connection.
27+* **Vector Indexing:** Ensure vector search indexes are properly created and maintained for efficient vector lookups (e.g., `vector_index` in `src/memory/storage.ts`). Note that Google embeddings are typically 768 dimensions.
28+* **Data Consistency:** Be mindful of data consistency when updating and retrieving memory components.
29+* **Scalability:** Consider the implications of memory storage on scalability for large-scale deployments.
30+* **Managing Conversation History:** Implement strategies to manage long conversation histories (e.g., trimming, summarizing) to prevent context window overflow and reduce costs. The `MessagesAnnotation` with `messagesStateReducer` is crucial for handling message updates and deletions.
31+* **Memory Store Usage:** Use the `Store` interface for cross-thread persistence. Define clear namespaces and keys for organizing memories. Implement semantic search for natural language retrieval.
32+* **Writing Memories:** Decide whether to write memories "on the hot path" (real-time, potentially impacting latency) or "in the background" (as a separate task).
33+* **Memory Representation:** Consider how memories are presented to the LLM (e.g., as updated instructions, few-shot examples) to optimize its performance.
4734
